Pagination
Page navigation for multi-page content. Provides page number links, previous/next controls, and first/last controls so users can step through long lists or search results. Reach for pagination whenever content is split into numbered pages.
Usage
When to use
- Long lists of results split across multiple pages
- Archives, search results, or content listings with a known total
- Any time the user benefits from jumping directly to a specific page
When not to use
- Infinite feeds where content loads as the user scrolls
- Short lists that fit on a single page
- Navigating between unrelated pages - use navbar instead
Do
- Show the current page clearly with
aria-current="page" - Include previous/next controls for sequential traversal
- Collapse long ranges with an ellipsis
Don't
- Hide the current page number from the visible control
- Use link text like "click here" for previous/next - use "Previous" and "Next" with
aria-label
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
items | object | - | Pagination entries grouped by role: first, previous, pages (keyed by page number), next, and last. Each boundary item has {text?, url} and pages is a map of page number to {url}. |
current | number | - | The active page number. Must match a key in items.pages. |
total_pages | number | - | Total number of pages. Used to derive disabled state on boundary controls. |
use_ellipsis | boolean | - | When true, inserts ellipsis markers between the page window and the first and last page. |
label | string | - | aria-label for the nav landmark. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
.rounded | Shape | - | Rounded corners. |
.square | Shape | - | Sharp corners. |
.pill | Shape | - | Fully rounded ends. |
Examples
Default
Basic pagination with page numbers and previous/next controls.
With first and last
Pagination with first and last controls in addition to previous/next.
Long range with ellipsis
Pagination collapsing a long range with an ellipsis indicator.
Disabled
Pagination on the first or last page with disabled previous/next controls.
Sizes
The three size values, which scale the font size and control padding together.
Shapes
The three shape values, which set the corner geometry of each control.
Accessibility
- WCAG 2.2 AA
- Wrapped in
<nav>labeled as pagination - Active page identified to assistive technology
- Disabled controls identified to assistive technology
- Previous/next controls have accessible names