Pagination
Preview appears after the next Storybook update.
<Pagination />When to use
Use it for
- Long, stable lists where users need to know where they are and jump back: token tables, audit logs.
- Below the list it controls, aligned with the list's start or end edge.
- compact in narrow spaces (side panels, mobile) and in card footers.
Not for
- Feeds the user skims once: load more or infinite scroll fit better.
- Fewer than about 25 items: show them all.
- Steps of a task: use a stepper.
Do and don't
Every example is rendered with the real component, so it always matches what ships.
Keep the page in the URL
Reloading or sharing the link should land on the same page. Control page and onPageChange from your router.
Hiding previous and next at the ends
Disabled previous on page 1 keeps the layout still and tells the user they are at the start.
Accessibility
- A nav landmark named "Pagination" (override with aria-label when a page has several).
- The current page button has aria-current="page" and an ink fill, not color alone.
- Page buttons are named "Page N"; previous and next are named "Previous page" and "Next page" and are disabled at the ends.
- Ellipses are icons hidden from assistive tech.
- In compact, the "Page 3 of 12" text is a polite live region, so page changes are announced.
Content guidelines
- Use "Previous" and "Next", not arrows alone or "Back" and "Forward".
- Show the total count of items near the list ("412 tokens"), not inside the pagination.
From the code Generated from the component, not editable here.
Anatomy and tokens
Read from packages/react/src/components/Pagination/Pagination.module.css at build time. Every value is a token: open one to see its alias chain in both themes.
- Navigation landmark
.pagination - sm
.sm - Page list (full)
.list, .compact - Page button
.page - Page button, hover
@media (hover: hover) .page:hover:not(.current) - Page button
.page:active:not(.current) - Page button, focus
.page:focus-visible - Current page
.current - Ellipsis
.ellipsis - Page N of M text
.status - Number in the status
.number
Motion and interaction
Pagination animates on hover and press. Try it in the preview at the top.
| Part | When | What changes | Duration | Easing |
|---|---|---|---|---|
| Full | Hover | Background | motion.duration.instant75 ms | motion.easing.standardsettles in place |
| Full | Press | Background | motion.duration.instant75 ms | motion.easing.standardsettles in place |
| Compact | Hover | Background | motion.duration.instant75 ms | motion.easing.standardsettles in place |
| Compact | Press | Background | motion.duration.instant75 ms | motion.easing.standardsettles in place |
With reduced motion turned on, every change happens at once.
From the code Generated from the component, not editable here.
Props
Parsed from the TypeScript types in packages/react/src/components/Pagination/Pagination.tsx, so this table cannot drift from the code.
| Prop | Type | Default | Description |
|---|---|---|---|
pageCountrequired | number | none | Total number of pages. |
page | number | none | Current page, 1-based (controlled). |
defaultPage | number | 1 | First page shown when uncontrolled. Default 1. |
onPageChange | (page: number) => void | none | Called with the requested page, 1-based. |
siblingCount | number | 1 | Pages shown on each side of the current one before an ellipsis. Default 1. |
variant | 'full' | 'compact' | 'full' | `full` lists page numbers; `compact` shows "Page 3 of 12" between previous and next (narrow spaces). Default `full`. |
size | 'sm' | 'md' | 'md' | Button height from the density tokens. Default `md`. |
Comes with getPageItems, each accepting native <div> attributes.
Playground
Change the props and see the real Pagination update. Controls are generated from the TypeScript props; nothing here changes the system.
<Pagination />Workbench
For contributors: every state with the accessibility panel, in the component workbench (Storybook). The stories double as visual test fixtures; the guidance on this page is the user documentation (open Pagination in Storybook).
Embed Storybook stories here (4)
Loads from https://bridge-storybook.floriangouloubi.com (set STORYBOOK_URL at build time). If Storybook is not running, the frames stay empty.
Default
Compact
Controlled
AllStates
From the code Generated from the component, not editable here.
Changelog
- New
The measure now writes the Figma sets drawn under a component's folder as their own entries, so Claude can fix them: popups drawn open (Dialog/Popup, AlertDialog/Popup, Drawer/Popup, Menu/Popup, Popover/Popup, Tooltip/Popup, and Select/Popup or Combobox/Popup, measured open when the stories show them closed) and sets that fix a prop (Pagination/Full, Pagination/Compact, Progress/Linear)
v1.0.0, Nov 11, 2026
- New
Navigation: Tabs (underline with a sliding signal indicator, contained, icons, counts, vertical), Breadcrumb (aria-current, collapsing middle levels), Pagination (full and compact, getPageItems helper) and SidebarNav (sections, collapsible groups, counts, current page mark)
v1.0.0, Nov 11, 2026