cotton
Core UI Kit
36

Pagination

Let users move through pages of results with numbered links and previous / next controls.

Basic Usage

Compose pagination with c-ui.pagination and place a c-ui.pagination.item for each page number. Mark the active page with :current="True" and use c-ui.pagination.ellipsis to collapse gaps in the range.

<c-ui.pagination>
    <c-ui.pagination.prev href="?page=1" />
    <c-ui.pagination.item href="?page=1">1</c-ui.pagination.item>
    <c-ui.pagination.item href="?page=2" :current="True">2</c-ui.pagination.item>
    <c-ui.pagination.item href="?page=3">3</c-ui.pagination.item>
    <c-ui.pagination.ellipsis />
    <c-ui.pagination.item href="?page=10">10</c-ui.pagination.item>
    <c-ui.pagination.next href="?page=3" />
</c-ui.pagination>
{% cotton ui.pagination %}
    {% cotton ui.pagination.prev href="?page=1" /%}
    {% cotton ui.pagination.item href="?page=1" %}1{% endcotton %}
    {% cotton ui.pagination.item href="?page=2" :current="True" %}2{% endcotton %}
    {% cotton ui.pagination.item href="?page=3" %}3{% endcotton %}
    {% cotton ui.pagination.ellipsis /%}
    {% cotton ui.pagination.item href="?page=10" %}10{% endcotton %}
    {% cotton ui.pagination.next href="?page=3" /%}
{% endcotton %}

Django Paginator

Pass a Django page_obj and the component renders the prev / numbered / next controls itself, with ellipses for large ranges. Set param if your page query string is not page.

<c-ui.pagination :page_obj="page_obj" />
{% cotton ui.pagination :page_obj="page_obj" /%}

For full control, omit page_obj and compose the sub-components yourself, as shown in the other examples.

Previous / Next

The c-ui.pagination.prev and c-ui.pagination.next arrows accept :disabled="True" to mute them and remove the link, for example on the first or last page.

<c-ui.pagination>
    <c-ui.pagination.prev href="?page=1" :disabled="True" />
    <c-ui.pagination.item href="?page=1" :current="True">1</c-ui.pagination.item>
    <c-ui.pagination.item href="?page=2">2</c-ui.pagination.item>
    <c-ui.pagination.item href="?page=3">3</c-ui.pagination.item>
    <c-ui.pagination.next href="?page=2" />
</c-ui.pagination>
{% cotton ui.pagination %}
    {% cotton ui.pagination.prev href="?page=1" :disabled="True" /%}
    {% cotton ui.pagination.item href="?page=1" :current="True" %}1{% endcotton %}
    {% cotton ui.pagination.item href="?page=2" %}2{% endcotton %}
    {% cotton ui.pagination.item href="?page=3" %}3{% endcotton %}
    {% cotton ui.pagination.next href="?page=2" /%}
{% endcotton %}

API Reference

Pagination

Name Description Type Options Default
page_obj A Django Page object. When given, the component renders prev / numbered / next controls itself instead of using the slot. Page — None
param Query string parameter used for page links in auto mode. str — page
class Extra classes merged onto the inner list. str —
slot (default) The pagination controls: items, ellipses and prev / next arrows. — —

Pagination.Item

Name Description Type Options Default
href Destination URL for the page. str —
current Mark the item as the active page. Renders with accent styling and aria-current='page'. bool — False
disabled Mute the item and remove its link. bool — False
class Extra classes merged onto the item's link. str —
slot (default) The page label, usually the page number. — —

Pagination.Prev / Pagination.Next

Name Description Type Options Default
href Destination URL for the previous or next page. str —
disabled Mute the arrow and remove its link, for example on the first or last page. bool — False
class Extra classes merged onto the arrow's link. str —

Pagination.Ellipsis

Name Description Type Options Default
class Extra classes merged onto the ellipsis span. str —
Theme
Accent
Ink