Theme
Version
GitHub PyPI Discord
On this page

Pagination

Use CPagination to move through a finite sequence while preserving native URLs or browser-local state.

Pagination at a glance

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

Put {page} in href. Server output then works before JavaScript and remains shareable.

Navigate with page links
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="{...}".

Control Pagination in the browser
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.

Compact long page ranges
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

Choose Pagination 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

Compare Pagination variants and sizes
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

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(...).

InputTypeDefaultEffect
pagesintrequiredSets the finite page count; must be at least 1.
pageint1Sets the current page between 1 and pages.
hrefstr | NoneNoneCreates native links by replacing a required {page} placeholder; None creates client-owned Buttons.
siblingsint1Keeps this many pages on either side of the current page.
boundariesint1Keeps this many pages at both sequence edges.
show_controlsboolTrueRenders previous and next controls.
show_edgesboolFalseRenders first and last controls.
disabledboolFalseDisables 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.
labelstr"Pagination"Names the navigation landmark.
page_labelstr"Page {page}"Labels numbered controls; must contain {page}.
previous_labelstr"Previous page"Labels the previous control.
next_labelstr"Next page"Labels the next control.
first_labelstr"First page"Labels the first control.
last_labelstr"Last page"Labels the last control.
class_CClassValue | None (CClassValue)NoneAdds root classes.
styleCStyleValue | None (CStyleValue)NoneAdds root inline styles.
attrsMapping[str, object] | NoneNoneAdds 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 />.

InputTypeOmitted behaviorEffect
pagenumber | undefinedUses the server input.Controls and rebuilds the current compact range while supplied.
disabledboolean | undefinedUses the server input.Overrides local disabled state while valid and supplied.
variant"soft" | "outline" | "plain" | undefinedUses the server input.Overrides visual treatment.
size"sm" | "md" | "lg" | undefinedUses the server input.Overrides control geometry.
onPageChange((page: number, detail: CPaginationChangeDetail) => void) | undefinedUses 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

EventSignatureTrigger and timingDetailControlled 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.

VariableTypePurposeDefault
--cui-pagination-gaplengthControl gap.0.35rem
--cui-pagination-control-sizelengthMinimum control width and height.Size-derived.
--cui-pagination-radiuslengthControl radius.0.55rem
--cui-pagination-foregroundcolorResting foreground.CanvasText
--cui-pagination-backgroundcolorResting background.transparent
--cui-pagination-border-colorcolorOutline border.Nested-scheme border color.
--cui-pagination-current-backgroundcolorCurrent-page background.Nested-scheme blue.
--cui-pagination-current-foregroundcolorCurrent-page foreground.Contrasting nested-scheme color.
--cui-pagination-disabled-opacitynumberDisabled opacity.0.5
--cui-pagination-focus-ringcolorKeyboard focus outline.Highlight

Attributes

HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.

CPagination attributes

AttributeElementTypeMeaning
aria-currentCurrent page control"page"Identifies the current page.
data-currentCurrent page controlpresent-or-absentPublic current-page styling hook.
data-pageControlinteger-stringTarget page.
data-kindControl"page" | "previous" | "next" | "first" | "last"Control job.
data-disabledRootpresent-or-absentPresent while navigation is disabled.
data-variantRoot"soft" | "outline" | "plain"Visual treatment.
data-sizeRoot"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

SelectorElementPurpose
[data-citry-ui-part="pagination"]nav rootStable root and attrs destination.
[data-citry-ui-part="list"]ulStable list layout.
[data-citry-ui-part="control"]link or ButtonStable interactive target.
[data-citry-ui-part="ellipsis"]inert spanStable omitted-range marker.

Interfaces

Aliases and data shapes referenced above.

Input type aliases

InterfaceDefinition
CClassValuestr | Mapping[str, bool] | Sequence[CClassValue]
CStyleValuestr | Mapping[str, str | int | float | bool | None] | Sequence[CStyleValue]
CPaginationVariantLiteral["soft", "outline", "plain"]
CPaginationSizeLiteral["sm", "md", "lg"]

CPaginationChangeDetail

FieldTypeDefaultMeaning
pagenumber-Requested page.
previousPagenumber-Current page before activation.
kind"page" | "previous" | "next" | "first" | "last"-Activated control job.
sourceEventEvent-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

KeyPurposeVariablesOverrideBrowser updates
citry-ui-pagination-labelNames the pagination navigation landmark.Nonelabel input$c-tr updates aria-label.
citry-ui-pagination-pageNames each numbered page control.page: strpage_label input$c-tr handles server controls; i18n.bind() handles recreated controls.
citry-ui-pagination-previousNames the previous-page control.Noneprevious_label input$c-tr or i18n.bind() updates aria-label.
citry-ui-pagination-nextNames the next-page control.Nonenext_label input$c-tr or i18n.bind() updates aria-label.
citry-ui-pagination-firstNames the first-page control.Nonefirst_label input$c-tr or i18n.bind() updates aria-label.
citry-ui-pagination-lastNames the last-page control.Nonelast_label input$c-tr or i18n.bind() updates aria-label.