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 native Vue bindings. Rebuilt Button ranges retain the server locale even without browser i18n; a client-enabled i18n provider also updates recreated labels when its locale changes.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class ControlledPagination(Component):
template = """
<section >
<p>Plate <strong v-text="page"></strong> of 18</p>
<c-CPagination
c-pages="18"
c-page="3"
:page="page"
:onPageChange="(next) => page = next"
/>
</section>
"""
js = """
$component({
data() {
return {
page: 3
};
},
});
"""
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-CCol 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-CCol>
"""
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-CCol 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-CCol>
"""
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-CCol 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-CCol>
"""
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
attrs accepts ordinary native, ARIA, and data attributes. It rejects the attributes the component sets itself (such as aria-label), Citry runtime attributes, and any Vue directive syntax: names starting with v-, :, ., ^, @, or #. Write Vue bindings and listeners on the component tag in your template instead, for example <c-CPagination :title="hint" @focusin="track">.
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. The filled-in URL must be a relative URL or an http:, https:, mailto:, sms:, or tel: URL; any other scheme raises ValueError. 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 native Vue :prop bindings 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 native Vue :prop bindings. Native browser events remain available through Vue @... 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; recreated controls use a fixed server-translated pattern without client i18n and i18n.bind() with it. |
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. |