Pagination
Use CPagination to move through a finite sequence while preserving native URLs or browser-local state.
Pagination at a glance
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class PaginationGlance(Component):
template = '<c-CPagination c-pages="24" c-page="8" href="?page={page}" />'
preview = PaginationGlance()
preview # noqa: B018
Navigate with links
Put {page} in href. Server output then works before JavaScript and remains shareable.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class LinkPagination(Component):
template = '<c-CPagination c-pages="12" c-page="4" href="/field-notes?page={page}" />'
preview = LinkPagination()
preview # noqa: B018
Control the current page in the browser
Omit href for Button controls. Client inputs are passed with $c-props="{...}".
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class ControlledPagination(Component):
template = """
<section x-data="{ page: 3 }">
<p>Plate <strong x-text="page"></strong> of 18</p>
<c-CPagination
c-pages="18"
c-page="3"
$c-props="{ page, onPageChange: (next) => page = next }"
/>
</section>
"""
preview = ControlledPagination()
preview # noqa: B018
Compact long ranges
siblings keeps pages around the current page. boundaries keeps pages at both ends.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class PaginationRanges(Component):
template = """
<c-CStack gap="md">
<c-CPagination c-pages="100" c-page="50" c-siblings="0" c-boundaries="1" />
<c-CPagination c-pages="100" c-page="50" c-siblings="2" c-boundaries="2" />
</c-CStack>
"""
preview = PaginationRanges()
preview # noqa: B018
Add edge controls
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class PaginationControls(Component):
template = """
<c-CStack gap="md">
<c-CPagination c-pages="14" c-page="7" c-show_edges="True" />
<c-CPagination c-pages="14" c-page="7" c-show_controls="False" />
</c-CStack>
"""
preview = PaginationControls()
preview # noqa: B018
Choose presentation
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class PaginationPresentation(Component):
template = """
<c-CStack gap="md">
<c-CPagination c-pages="8" c-page="3" variant="soft" size="sm" />
<c-CPagination c-pages="8" c-page="3" variant="outline" />
<c-CPagination c-pages="8" c-page="3" variant="plain" size="lg" />
</c-CStack>
"""
preview = PaginationPresentation()
preview # noqa: B018
Customize Pagination
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class PaginationCustomization(Component):
template = '<c-CPagination class_="lunar-pages" c-pages="9" c-page="5" />'
css = """
:where(.lunar-pages) {
--cui-pagination-current-background: light-dark(#6d28d9, #c4b5fd);
--cui-pagination-current-foreground: light-dark(white, #2e1065);
--cui-pagination-radius: 999px;
}
"""
preview = PaginationCustomization()
preview # noqa: B018
Accessibility and behavior
Pagination is a named navigation landmark. Current page uses aria-current="page". Links and Buttons keep native Tab and activation behavior; ellipses are inert.
API reference
Inputs
CPagination server inputs
Server inputs are passed in a template through <c-CPagination ... /> or in Python through CPagination(...).
| Input | Type | Default | Effect |
|---|---|---|---|
pages | int | required | Sets the finite page count; must be at least 1. |
page | int | 1 | Sets the current page between 1 and pages. |
href | str | None | None | Creates native links by replacing a required {page} placeholder; None creates client-owned Buttons. |
siblings | int | 1 | Keeps this many pages on either side of the current page. |
boundaries | int | 1 | Keeps this many pages at both sequence edges. |
show_controls | bool | True | Renders previous and next controls. |
show_edges | bool | False | Renders first and last controls. |
disabled | bool | False | Disables all Button-mode controls and removes link navigation. |
variant | "soft" | "outline" | "plain" (CPaginationVariant) | "soft" | Selects visual treatment. |
size | "sm" | "md" | "lg" (CPaginationSize) | "md" | Selects control geometry. |
label | str | "Pagination" | Names the navigation landmark. |
page_label | str | "Page {page}" | Labels numbered controls; must contain {page}. |
previous_label | str | "Previous page" | Labels the previous control. |
next_label | str | "Next page" | Labels the next control. |
first_label | str | "First page" | Labels the first control. |
last_label | str | "Last page" | Labels the last control. |
class_ | CClassValue | None (CClassValue) | None | Adds root classes. |
style | CStyleValue | None (CStyleValue) | None | Adds root inline styles. |
attrs | Mapping[str, object] | None | None | Adds copied trusted nav attributes without replacing naming, children, focus ownership, or runtime fields. |
CPagination client inputs
Client inputs are passed in the browser through the $c-props="{ ... }" attribute on <c-CPagination />.
| Input | Type | Omitted behavior | Effect |
|---|---|---|---|
page | number | undefined | Uses the server input. | Controls and rebuilds the current compact range while supplied. |
disabled | boolean | undefined | Uses the server input. | Overrides local disabled state while valid and supplied. |
variant | "soft" | "outline" | "plain" | undefined | Uses the server input. | Overrides visual treatment. |
size | "sm" | "md" | "lg" | undefined | Uses the server input. | Overrides control geometry. |
onPageChange | ((page: number, detail: CPaginationChangeDetail) => void) | undefined | Uses the server input. | Runs before accepted Button state changes or native link navigation. |
Slots
-
Events
Component events are callback inputs supplied through $c-props. Native browser events remain available through Alpine @... attributes.
CPagination events
| Event | Signature | Trigger and timing | Detail | Controlled and cancellation behavior |
|---|---|---|---|---|
onPageChange | (page: number, detail: CPaginationChangeDetail) => void (CPaginationChangeDetail) | Enabled noncurrent control activation. | {page, previousPage, kind, sourceEvent} (CPaginationChangeDetail) | Reports the target before Button state change or link navigation; preventing sourceEvent prevents a link. |
Methods
-
CSS
CSS variables to theme the components. Set them on an ancestor or the component itself.
CPagination CSS variables
Apply these variables to CPagination or one of its ancestors.
| Variable | Type | Purpose | Default |
|---|---|---|---|
--cui-pagination-gap | length | Control gap. | 0.35rem |
--cui-pagination-control-size | length | Minimum control width and height. | Size-derived. |
--cui-pagination-radius | length | Control radius. | 0.55rem |
--cui-pagination-foreground | color | Resting foreground. | CanvasText |
--cui-pagination-background | color | Resting background. | transparent |
--cui-pagination-border-color | color | Outline border. | Nested-scheme border color. |
--cui-pagination-current-background | color | Current-page background. | Nested-scheme blue. |
--cui-pagination-current-foreground | color | Current-page foreground. | Contrasting nested-scheme color. |
--cui-pagination-disabled-opacity | number | Disabled opacity. | 0.5 |
--cui-pagination-focus-ring | color | Keyboard focus outline. | Highlight |
Attributes
HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.
CPagination attributes
| Attribute | Element | Type | Meaning |
|---|---|---|---|
aria-current | Current page control | "page" | Identifies the current page. |
data-current | Current page control | present-or-absent | Public current-page styling hook. |
data-page | Control | integer-string | Target page. |
data-kind | Control | "page" | "previous" | "next" | "first" | "last" | Control job. |
data-disabled | Root | present-or-absent | Present while navigation is disabled. |
data-variant | Root | "soft" | "outline" | "plain" | Visual treatment. |
data-size | Root | "sm" | "md" | "lg" | Control geometry. |
Selectors
Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.
CPagination selectors
| Selector | Element | Purpose |
|---|---|---|
[data-citry-ui-part="pagination"] | nav root | Stable root and attrs destination. |
[data-citry-ui-part="list"] | ul | Stable list layout. |
[data-citry-ui-part="control"] | link or Button | Stable interactive target. |
[data-citry-ui-part="ellipsis"] | inert span | Stable omitted-range marker. |
Interfaces
Aliases and data shapes referenced above.
Input type aliases
| Interface | Definition |
|---|---|
CClassValue | str | Mapping[str, bool] | Sequence[CClassValue] |
CStyleValue | str | Mapping[str, str | int | float | bool | None] | Sequence[CStyleValue] |
CPaginationVariant | Literal["soft", "outline", "plain"] |
CPaginationSize | Literal["sm", "md", "lg"] |
CPaginationChangeDetail
| Field | Type | Default | Meaning |
|---|---|---|---|
page | number | - | Requested page. |
previousPage | number | - | Current page before activation. |
kind | "page" | "previous" | "next" | "first" | "last" | - | Activated control job. |
sourceEvent | Event | - | Native click event; prevent it to stop a link. |
Translation keys
Catalog keys used by this family. An explicit component input or slot listed in Override takes precedence over the catalog for that instance.
CPagination translation keys
| Key | Purpose | Variables | Override | Browser updates |
|---|---|---|---|---|
citry-ui-pagination-label | Names the pagination navigation landmark. | None | label input | $c-tr updates aria-label. |
citry-ui-pagination-page | Names each numbered page control. | page: str | page_label input | $c-tr handles server controls; i18n.bind() handles recreated controls. |
citry-ui-pagination-previous | Names the previous-page control. | None | previous_label input | $c-tr or i18n.bind() updates aria-label. |
citry-ui-pagination-next | Names the next-page control. | None | next_label input | $c-tr or i18n.bind() updates aria-label. |
citry-ui-pagination-first | Names the first-page control. | None | first_label input | $c-tr or i18n.bind() updates aria-label. |
citry-ui-pagination-last | Names the last-page control. | None | last_label input | $c-tr or i18n.bind() updates aria-label. |