Pagination

Moves between pages of a long list.

When to use

A long list split into pages users move through in order: an audit log, a record search.
Users need to come back to a given page, so each page has its own URL.

When not to use

A list that fits on one screen: show all of it.
Moving back up a hierarchy: use Breadcrumb.
A few rows under a table: Previous and Next Buttons with a row count are enough.

Install

npx shadcn@latest add @clinia/pagination

Anatomy

Clinia rules

The current page is isActive: an outline button with a Trust border (border-emphasis). The other pages are ghost.
Show the first page, the last page, the current page and its neighbours. Collapse the gaps with PaginationEllipsis.
Previous and Next hide their text below sm and keep the arrow. On a French page, pass text="Précédent" and text="Suivant".

Do and don't

Do show the first and last pages, the current page and its neighbours.

Don't list every page number.

Accessibility

Built in

The current page has aria-current="page" and a Trust border, at least 3:1 in both themes.
Renders a <nav> landmark labelled pagination, with the pages in a list.
Previous and Next carry an aria-label (Go to previous page), so they keep a name when the visible text hides on small screens.
The ellipsis is hidden from screen readers.

Your responsibility

Give every page link a real href, so it works without JavaScript and opens in a new tab.
When you pass French text, also pass a French aria-label (Aller à la page précédente): the default label stays English.
On the first or last page, remove Previous or Next rather than leaving a link that goes nowhere.

How to test

Press Tab through the pages: each link shows the focus ring.
With a screen reader, the current page is announced as 2, current page, link.
Narrow the window below 640px: Previous and Next show only arrows, and a screen reader still reads Go to previous page.

API

PaginationLink

Prop	Values	Default	Description
isActive	`boolean`	–	Marks the current page: sets `aria-current` and an `accent` border.

PaginationNext

Prop	Values	Default	Description
text	`string`	`Next`	Visible label next to the arrow, such as "Précédent" or "Suivant" on a French page.

PaginationPrevious

Prop	Values	Default	Description
text	`string`	`Previous`	Visible label next to the arrow, such as "Précédent" or "Suivant" on a French page.

All other props come from the native nav element.