Pagination
The control that moves between the numbered pages of one list or table whose page count is known.
Installation
npx shadcn@latest add @flyingsalmon/paginationUsage
import { useState } from 'react'
import { Pagination } from '@/components/ui/pagination'
export function PaginationUsage() {
const [page, setPage] = useState(1)
return <Pagination page={page} pageCount={12} onPageChange={setPage} />
}Examples
Short list
Five pages fit in the seven slots, so every page shows and no ellipsis appears. The component decides from pageCount; there is nothing to configure.
Compact
Where the row has no space for numbers (a toolbar, a card footer, a phone-width list) the numbers give way to the position. Previous and next keep their size.
Custom position text
formatPageLabel writes the compact text yourself, for another wording or another language.
Links
Each item is a router link and the page it shows comes from this page's own URL. Move it and the address bar moves with it.
Under a table
Pagination is the control, not the data. It sits right-aligned under the table it pages; the slicing and the fetching stay in your app.
| Place | Neighbourhood | Day |
|---|---|---|
| Fushimi Inari | Fushimi | Day 1 |
| Kiyomizu-dera | Higashiyama | Day 1 |
| Nishiki Market | Nakagyo | Day 1 |
Guidelines
When to use
- To page through one list or table whose page count is known, such as the places saved to a trip.
- When the traveller needs to land on a specific page and come back to it, in the URL or in state.
When not to use
- Use Stepper for a position in a short sequence someone is walking, because stepper only shows where they are and never navigates.
- Use Breadcrumb to climb the levels above the current page, because pagination moves across siblings and never up.
- Use Tabs to move between peer panels of content rather than pages of data.
Do and don’t
- DoRight-align pagination under the list it pages, once per list.It waits where the traveller finishes reading. A second copy above the list is one more thing to scan and nothing new to do.
- DoKeep the page number in the address whenever the traveller can land on a page.A page in the URL can be bookmarked, shared, opened in a new tab, and reloaded, so the traveller comes back to the page they left rather than to page 1.
- DoWrite a line such as "1 to 20 of 240" beside the list when the traveller needs the total.Pagination shows where the traveller is, not how much there is. Only the app knows the size of its data.
- Don’tShow pagination on a list that fits on one page.A row with one number offers a choice that is not there, so a one-page list simply ends.
- Don’tPage a short list that grouping or filtering would keep on one screen.Trips split into upcoming and past stay in view together. A page break hides half of them behind a press.
Accessibility
| Key | Description |
|---|---|
| Tab | Moves through previous, the page items, and next. A disabled previous or next takes no focus. |
| EnterSpace | Activates the focused item. On the current page it changes nothing and focus stays put. |
The root is a nav named “Pagination”; aria-label overrides the name. Each page item is named “Page 5” and the current one carries aria-current="page". Previous and next are named “Previous page” and “Next page”, the ellipsis is hidden from the accessibility tree, and the compact text is a polite live region, so a screen reader hears the new position without being interrupted.
There are no arrow keys: pagination is a navigation region of independent controls, not a composite widget. Items are keyed by page number, so focus stays on the page you activated even when the window shifts around it and you can keep stepping without hunting for focus.
API
Pagination
Controlled: the row count, the page size, and the fetching stay in your app, and so do “Load more”, infinite scroll, a page-size select, and a range line. Also takes every <nav> attribute except children.
| Prop | Type | Default | Description |
|---|---|---|---|
| page | number | Required | The current page, counting from 1. |
| pageCount | number | Required | The number of pages. A value of 1 or less renders nothing. |
| onPageChange | (page: number) => void | – | Called with the target page. It is not called for the current page. |
| compact | boolean | false | Replaces the page numbers with the position text between previous and next. The component never measures its width and has no breakpoint, so you choose compact where the row has no room for numbers: a toolbar, a card footer, a phone-width list. |
| formatPageLabel | (page: number, pageCount: number) => string | "Page {page} of {pageCount}" | Writes the compact position text. |
| renderPageLink | (page: number, children: ReactNode) => ReactNode | – | Renders each page item and each enabled previous or next as the anchor you return. Pass it when the page lives in the URL. A disabled previous or next stays a plain span. |
| aria-label | string | "Pagination" | The name of the nav landmark. |