Navigation
Pagination
Pagination is a paged navigation control with Previous/Next boundaries, numbered pages, and optional ellipsis.
Composed from Page Item states — Default/Hover/Current/Disabled
betaReact AvailableFigma AvailableDocs Partial
- React last updated
- 2026-07-11
- Documentation last updated
- 2026-06-01
- Accessibility target
- WCAG 2.2 AA (target)
- Version
- 0.4.0-beta
Known open questions
- Responsive collapsed pagination is not confirmed in Figma — sibling/boundary range only.
Live preview
Link-based pagination for URL-addressable pages.
Href builder
Button-based client state
Current preview page: 3. Ellipsis items are non-interactive and include hidden "More pages" text.
Purpose
Changes the visible page within a paged collection or result set using numbered controls and Previous/Next boundaries.
Anatomy
Pagination = nav landmark + previous + numbered pages + ellipsis + next.
Variants and states
link · button
When to use
Search results, tables, or galleries where users move between discrete pages of content.
When not to use
Infinite scroll or "Load more" patterns without discrete page URLs.
Accessibility
nav aria-label="Pagination". Current page uses aria-current="page". Previous/Next have explicit labels. Ellipsis is non-interactive.
Keyboard behavior
Focusable page links/buttons and boundary controls. Current page is non-interactive text.
Common mistakes
Rendering anchors without href values. Using buttons when pages are URL-addressable.
Properties
Previous, numbered pages, ellipsis, and Next composed from Page Item patterns.
Should Pagination use links or buttons?
Use links when pages have real URLs. Use buttons for client-managed collections without addressable pages.
What is the difference between Pagination and infinite scroll?
Pagination exposes discrete pages with explicit current location. Infinite scroll appends content without page landmarks.
Tokens used
semantic/text/secondarysemantic/action/primarysemantic/surface/elevated
Component API
| Prop | Type | Default | Description |
|---|---|---|---|
| items | PaginationItem[] | — | Explicit pagination controls. |
| onPageChange | (page: number) => void | — | Button-based page changes. |
React example
Copy React example
import { Pagination, buildPaginationItems } from "@/components/ui/Pagination";
export function Example() {
const items = buildPaginationItems({
currentPage: 3,
totalPages: 12,
hrefBuilder: (page) => `/results?page=${page}`,
});
return <Pagination items={items} />;
}