Pagination

Usage

Overview

Pagination navigates between pages of a result set. It renders a Page {page} of {pageCount} label at left and a set of controls at right. It ships as a controlled component — the caller owns page and responds to onPageChange — and supports two types: PaginationType.Simple (Previous/Next buttons) and PaginationType.Numbered (chevron controls plus numbered page buttons with ellipsis truncation). Simple is the only type that supports an unknown total page count, which makes it the right choice for cursor-based pagination. DataTable uses Simple internally for its built-in pagination footer.

When to use

Navigating between pages of a table, list, or search results.
Cursor-based pagination where the total number of pages is not known ahead of time — use Simple.
Large result sets where jumping directly to a specific page is useful — use Numbered.

When not to use

Infinite scroll or "load more" patterns — those replace pagination entirely rather than complementing it.
Wizards or multi-step forms — use a stepper or SegmentedControl instead, since those steps are not interchangeable pages of the same content.
Tabs between unrelated views — use Tabs or Tabs.

Content guidelines

Keep the label to the default Page {page} of {pageCount} (or Page {page} when the total is unknown) — it is already localized and formats numbers per locale.
Numbered page labels are always the locale-formatted page number; do not substitute custom text.

Behavior and states

Controlled only. Pagination does not track its own page state — the caller supplies page and updates it in onPageChange.
Unknown page count. Omit pageCount (or pass -1) with PaginationType.Simple when the total is not known, e.g. cursor-based pagination. The label degrades to Page {page} and the Next control stays enabled rather than prematurely disabling.
Boundary disabling. Previous disables on page 1; Next disables on the last page (only when the total is known).
Ellipsis truncation. PaginationType.Numbered always shows the first and last page. With the default siblingCount of 1, boundary pages show 6 slots (1 2 3 4 … 10) and middle pages show 7 (1 … 4 5 6 … 10) — two ellipses plus symmetric siblings cannot fit in 6 slots.
Hiding the label. Pass hideLabel to render only the controls, right-aligned.

Best practices

Move focus to the first row or item of the new page after onPageChange fires, so keyboard and screen reader users land somewhere meaningful.
Use Numbered when users benefit from jumping to a specific page, not just stepping through sequentially.
Use Simple for cursor-based or streaming data sources where the total page count is not known.

Don't

Don't pass a pageCount to Numbered that you can't compute reliably — Numbered requires a known total.
Don't build a custom Previous/Next control when Pagination already covers boundary disabling and localization.

Accessibility

Pagination renders a <nav> landmark with an accessible name, and Numbered renders page numbers in an <ol> with aria-current="page" on the active item. See Accessibility for the full contract.

Table and Data Table — DataTable renders Pagination internally for its built-in pagination footer.

Number Field / Accessibility

Pagination / API and Development

On this page

Pagination

Usage

Overview

When to use

Navigating between pages of a table, list, or search results.
Cursor-based pagination where the total number of pages is not known ahead of time — use Simple.
Large result sets where jumping directly to a specific page is useful — use Numbered.

When not to use

Infinite scroll or "load more" patterns — those replace pagination entirely rather than complementing it.
Wizards or multi-step forms — use a stepper or SegmentedControl instead, since those steps are not interchangeable pages of the same content.
Tabs between unrelated views — use Tabs or Tabs.

Content guidelines

Keep the label to the default Page {page} of {pageCount} (or Page {page} when the total is unknown) — it is already localized and formats numbers per locale.
Numbered page labels are always the locale-formatted page number; do not substitute custom text.

Behavior and states

Controlled only. Pagination does not track its own page state — the caller supplies page and updates it in onPageChange.
Unknown page count. Omit pageCount (or pass -1) with PaginationType.Simple when the total is not known, e.g. cursor-based pagination. The label degrades to Page {page} and the Next control stays enabled rather than prematurely disabling.
Boundary disabling. Previous disables on page 1; Next disables on the last page (only when the total is known).
Ellipsis truncation. PaginationType.Numbered always shows the first and last page. With the default siblingCount of 1, boundary pages show 6 slots (1 2 3 4 … 10) and middle pages show 7 (1 … 4 5 6 … 10) — two ellipses plus symmetric siblings cannot fit in 6 slots.
Hiding the label. Pass hideLabel to render only the controls, right-aligned.

Best practices

Move focus to the first row or item of the new page after onPageChange fires, so keyboard and screen reader users land somewhere meaningful.
Use Numbered when users benefit from jumping to a specific page, not just stepping through sequentially.
Use Simple for cursor-based or streaming data sources where the total page count is not known.

Don't

Don't pass a pageCount to Numbered that you can't compute reliably — Numbered requires a known total.
Don't build a custom Previous/Next control when Pagination already covers boundary disabling and localization.

Accessibility

Table and Data Table — DataTable renders Pagination internally for its built-in pagination footer.

Number Field / Accessibility

Pagination / API and Development

On this page