Pagination

Implemented Navigation

A page navigation component for navigating through paginated content.

Kumo reference: kumo-ui.com/components/pagination/

Presentation commands show demo feedback. Read the interaction guide to connect real actions.

Full Controls (Default)

The default pagination includes first, previous, page input, next, and last buttons.

Showing 1-10 of 100

Show template

{% load wdj %}
{% include "wdj/components/pagination.html" with page=1 per_page=10 total_count=100 controls="full" %}

Simple Controls

Use controls="simple" for a minimal pagination with only previous and next buttons.

Showing 1-10 of 100

Show template

{% load wdj %}
{% include "wdj/components/pagination.html" with page=1 per_page=10 total_count=100 controls="simple" %}

Unknown Totals

Use has_next_page when the data source does not return a total count. Common for cursor-based APIs where calculating the total is expensive.

Page 1

Show template

{% load wdj %}
{% include "wdj/components/pagination.html" with page=1 has_next_page=True text="Page 1" %}

Mid-Page State

Pagination in the middle of a dataset with all navigation enabled.

Showing 41-50 of 100

Show template

{% load wdj %}
{% include "wdj/components/pagination.html" with page=5 per_page=10 total_count=100 %}

Large Dataset

Pagination handles large datasets with many pages.

Showing 1-25 of 1250

Show template

{% load wdj %}
{% include "wdj/components/pagination.html" with page=1 per_page=25 total_count=1250 %}

Custom Text

You can set custom pagination text.

Page 1 - showing 25 per page

Show template

{% load wdj %}
{% include "wdj/components/pagination.html" with page=1 per_page=25 total_count=100 text="Page 1 - showing 25 per page" %}

Compound Components

For more control over layout and features, use the compound component API. This allows you to compose Pagination.Info, Pagination.PageSize, Pagination.Controls, and Pagination.Separator in any order.

Page Size Selector

Add a dropdown to let users select the number of items per page using compound subcomponents.

Showing 1-25 of 500

Per page:

Show template

{% load wdj %}
{% wdj_component "wdj/components/pagination.html" page=1 per_page=25 total_count=500 %}
  {% include "wdj/components/pagination_info.html" with page=1 per_page=25 total_count=500 only %}
  {% include "wdj/components/pagination_separator.html" only %}
  {% include "wdj/components/pagination_page_size.html" with value=25 only %}
  {% include "wdj/components/pagination_controls.html" with page=1 per_page=25 total_count=500 only %}
{% endwdj_component %}

Custom Page Size Options

Customize the available page size options with the options prop. Defaults to [25, 50, 100, 250].

Showing 1-10 of 200

Per page:

Show template

{% load wdj %}
{% wdj_component "wdj/components/pagination.html" page=1 per_page=10 total_count=200 %}
  {% include "wdj/components/pagination_info.html" with page=1 per_page=10 total_count=200 only %}
  {% include "wdj/components/pagination_separator.html" only %}
  {% include "wdj/components/pagination_page_size.html" with value=10 options=custom_page_sizes only %}
  {% include "wdj/components/pagination_controls.html" with page=1 per_page=10 total_count=200 only %}
{% endwdj_component %}

Custom Info Text

Use custom text to format the page and item counts.

Page 1 of 4

Show template

{% load wdj %}
{% wdj_component "wdj/components/pagination.html" page=1 per_page=25 total_count=100 text="Page 1 of 4" %}
  {% include "wdj/components/pagination_info.html" with text="Page 1 of 4" only %}
  {% include "wdj/components/pagination_controls.html" with page=1 per_page=25 total_count=100 only %}
{% endwdj_component %}

Custom Layout

Arrange components in any order. Here the page size selector is on the right.

Showing 1-25 of 500

Per page:

Show template

{% load wdj %}
{% wdj_component "wdj/components/pagination.html" page=1 per_page=25 total_count=500 %}
  {% include "wdj/components/pagination_info.html" with page=1 per_page=25 total_count=500 only %}
  <div class="flex flex-wrap items-center gap-2">
    {% include "wdj/components/pagination_controls.html" with page=1 per_page=25 total_count=500 only %}
    {% include "wdj/components/pagination_separator.html" only %}
    {% include "wdj/components/pagination_page_size.html" with value=25 only %}
  </div>
{% endwdj_component %}

Dropdown Page Selector

Use page_selector="dropdown" to render a dropdown select instead of a text input for page navigation.

Showing 1-25 of 500

Per page:

Show template

{% load wdj %}
{% wdj_component "wdj/components/pagination.html" page=1 per_page=25 total_count=500 %}
  {% include "wdj/components/pagination_info.html" with page=1 per_page=25 total_count=500 only %}
  {% include "wdj/components/pagination_separator.html" only %}
  {% include "wdj/components/pagination_page_size.html" with value=25 only %}
  {% include "wdj/components/pagination_controls.html" with page=1 per_page=25 total_count=500 page_selector="dropdown" only %}
{% endwdj_component %}

Internationalization

Use the labels prop to customize all UI strings for different locales. All labels default to English.

Affichage de 1-10 sur 100

Show template

{% load wdj %}
{% wdj_component "wdj/components/pagination.html" page=1 per_page=10 total_count=100 %}
  <div aria-live="polite" aria-atomic="true" data-slot="pagination-info" data-wdj-i18n class="text-base text-kumo-subtle">
    Affichage de <span class="tabular-nums">1-10</span> sur <span class="tabular-nums">100</span>
  </div>
  {% include "wdj/components/pagination_controls.html" with page=1 per_page=10 total_count=100 labels=french_labels only %}
{% endwdj_component %}

API Reference

Prop	Type	Default	Description
page	int	1	Current page number (1-indexed).
per_page	int	10	Number of items displayed per page.
total_count	int	None	Total number of items across all pages.
total_pages	int	None	Total number of pages (derived from total_count / per_page if omitted).
has_next_page	bool	None	Whether another page exists when total count is unknown (cursor pagination).
controls	"full" \| "simple"	"full"	Controls mode: full (first, prev, input, next, last) or simple (prev, next).
page_selector	"input" \| "dropdown"	"input"	How page selector renders: text input or select dropdown.
text	str	None	Custom info string overriding "Showing X-Y of Z".
page_sizes	list[int]	None	Available page size choices, e.g. [10, 20, 50] or [25, 50, 100, 250].
page_size	int	25	Current selected page size.
page_size_label	str	"Per page:"	Label text displayed before the page size dropdown.
page_size_right	bool	False	Whether to place the page size selector on the right of controls.
labels	dict	{}	Aria labels for internationalization (first_page, previous_page, next_page, last_page, page_number, page_size, navigation).
base_url	str	None	Base URL used to build anchor links for sequential navigation.
param	str	"page"	Query parameter name for current page.
hx_target	str	None	HTMX target CSS selector for fragment swaps.
hx_swap	str	"outerHTML"	HTMX swap strategy.

Accessibility notes

Every interactive component keeps real semantics and keyboard support: native controls where possible, ARIA only where necessary, and a visible focus ring. See the Accessibility page for the shared contract.

Read the accessibility contract