Navigation
Pagination
Moves through long lists a page at a time — the natural footer for the Table. A live range summary, windowed page numbers that collapse to ellipses, and an optional rows-per-page control.
npx shadcn@latest add @orbit/paginationOverview
All three parts together: range summary, rows-per-page popover, and windowed page navigation.
Windowed page numbers
The first and last page are always visible; the current page sits in a window of siblings, and any gap collapses to an ellipsis. The set stays a steady width no matter the page.
Variants & sizes
Numbered for browsable lists, compact when space is tight, and labeled prev / next for simple flows. Two sizes match table and toolbar density.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| total | number | — | Total number of items being paged. |
| page / defaultPage | number | 1 | Controlled / initial current page (1-based, clamped to the page count). |
| onPageChange | (page: number) => void | — | Called with the new page after prev/next, a number, or a size change moves it. |
| pageSize / defaultPageSize | number | 10 | Controlled / initial rows per page. |
| onPageSizeChange | (pageSize: number) => void | — | Called when a new size is picked. The page adjusts to keep the first visible row in view. |
| siblings | number | 1 | Pages shown on each side of the current page in the window. |
| variant | "numbered" | "compact" | "numbered" | Windowed page buttons, or a compact “Page n of m” readout. |
| size | "sm" | "md" | "md" | Button height 30px (sm) / 34px (md). |
| summary | boolean | true | Show the “Showing x–y of z” range summary. |
| pageSizeSelect | boolean | true | Show the rows-per-page popover (options via pageSizeOptions, default 10/20/50/100). |
| labeledNav | boolean | false | Add “Prev” / “Next” labels beside the chevrons. |
| …rest | HTMLAttributes | — | Everything else is forwarded to the root <div>, including ref. |
Usage
Pagination should make the size of a list obvious and the next step effortless.
Always show the total
The range summary tells people how big the list is and where they are in it.
Render every page number
Past ~7 pages, collapse the middle to ellipses so the control keeps a fixed width.
Disable, don't hide, the ends
Keep prev / next in place and disabled at the boundaries so the layout never jumps.
Reset to page 1 on size change
When rows-per-page changes, keep the first visible row in view instead of jumping.
Keyboard & accessibility
A nav landmark labeled “Pagination”; every control is a real button with a visible focus ring, tabular numerals keep widths steady, and the rows-per-page popover is an ARIA menu (arrows, Escape).