Pagination
Pagination allows users to move between the pages of a list by number, or to the previous and the next page.
When to Use
- for a Table or a list that is split into pages, placed under it and next to a count such as “Showing 1 to 12 of 48”
- when each page has its own URL, as the parts are links with an
href
When Not to Use
- to step through slides in place, without loading a page (use a Carousel)
- for a few fixed views of one list, such as “Invoices” and “Estimates” (use Tabs)
- to show the path from the home page to the current page (use a Breadcrumb)
Anatomy
| Element | Usage |
|---|---|
| Previous | Optional |
| Current page | Required |
| Next | Optional |
| Page link | Optional |
| Ellipsis | Optional |
The links are a elements styled as a Button. The ellipsis represents the pages that are omitted, and it isn’t a link.
States
On the first page, set aria-disabled on PaginationPrevious, and on the last page, set it on PaginationNext. A disabled link has no href and can’t be clicked or receive focus.
Behavior
Pagination renders the links that you pass to it. It doesn’t count pages, choose which numbers to show, or change the page. You set the href of each link, the numbers to show, where an ellipsis marks a gap, and which link is current.
Below 640px, PaginationPrevious and PaginationNext show only their caret.
Position
By default, Pagination fills the width of its container and centers its links. To place it at the end of a row, next to a count, set className="mx-0 w-auto".
Content
The labels are in labels.pagination. To translate them, use the Summit Provider.
Accessibility
The links are native a elements, so the browser provides their role and their keys.
Requirements
Set isActive on the link of the current page. It adds aria-current="page", which is the only way screen reader users can tell which page is current.
Installation
npx shadcn@latest add @summit/paginationThe CLI also adds @summit/button and @summit/summit-provider.
Usage
import {
Pagination,
PaginationContent,
PaginationEllipsis,
PaginationItem,
PaginationLink,
PaginationNext,
PaginationPrevious,
} from '@/components/ui/pagination';
<Pagination>
<PaginationContent>
<PaginationItem>
<PaginationPrevious href="/invoices?page=1" />
</PaginationItem>
<PaginationItem>
<PaginationLink href="/invoices?page=1">1</PaginationLink>
</PaginationItem>
<PaginationItem>
<PaginationLink href="/invoices?page=2" isActive>
2
</PaginationLink>
</PaginationItem>
<PaginationItem>
<PaginationEllipsis />
</PaginationItem>
<PaginationItem>
<PaginationLink href="/invoices?page=8">8</PaginationLink>
</PaginationItem>
<PaginationItem>
<PaginationNext href="/invoices?page=3" />
</PaginationItem>
</PaginationContent>
</Pagination>;Change a Label
To change the visible label, set text on PaginationPrevious or PaginationNext. The same words become the link’s accessible name.
<PaginationNext href="/invoices?page=3" text="Older" />API Reference
The parts accept the props of the elements they render.
PaginationLink
| Prop | Type | Default | Description |
|---|---|---|---|
isActive | boolean | None | Marks the current page with aria-current="page" and the outline variant |
size | A size of Button | 'icon' | The size of the link |
PaginationPrevious and PaginationNext
| Prop | Type | Default | Description |
|---|---|---|---|
text | string | labels.pagination.previous or labels.pagination.next | The visible label |
Both accept the props of PaginationLink and set size to default.