Centred page buttons with previous and next, gaps for long ranges, and a summary line at the left.
Pagination is the pager that sits under every Table, documented on its own because it works under any list: cards, search results, an activity feed. The page buttons stay on the centre line whatever the summary's length (a 1fr auto 1fr grid), and long ranges collapse into gaps around the current page.
With totalItems and pageSize it says "Showing 41 to 60 of 236 orders"; without, "Page 3 of 12". It is presentational: the screen owns the page number.
Usage
import { Pagination } from "@/components/ui";
<Pagination page={page} pageCount={12} onPageChange={setPage} totalItems={236} pageSize={20} itemLabel="orders" />Examples
With a summary
Pages only
API
Generated from the component's TypeScript types and JSDoc (scripts/gen-ui-registry.mjs), so it always matches the source.
Pagination
| Prop | Type | Default | Description |
|---|---|---|---|
| pageRequired | number | ||
| pageCountRequired | number | ||
| onPageChangeRequired | (page: number) => void | ||
| totalItems | number | ||
| pageSize | number | ||
| itemLabel | string | "results" | Plural noun for the summary: "customers", "requests". |
| className | string |
Theme tokens
Per-component tokens are undeclared by default, so the default shown is the fallback the CSS uses. Set one at :root (or in theme.css) to restyle every instance. Live values are read from this page, so they follow the Rime Studio.
| Token | Default | Live value |
|---|---|---|
| --button-primary-bg | var(--brand-gradient) | … |
| --button-radius | var(--r-sm) | … |
| --inner-radius | var(--r-lg) | … |
| --r-flat | var(--table-radius, var(--r-md)) / var(--table-radius, var(--inner-radius, var(--r-lg))) | … |
| --table-radius | var(--r-md) / var(--inner-radius, var(--r-lg)) | … |
| --table-row-height | 46px | … |
System tokens it reads
| Token | Default | Live value |
|---|---|---|
| --brand-deep | tokens.css | … |
| --brand-gradient | tokens.css | … |
| --control-h-sm | tokens.css | … |
| --dur | tokens.css | … |
| --ease | tokens.css | … |
| --focus-color | tokens.css | … |
| --focus-ring | tokens.css | … |
| --font-mono | tokens.css | … |
| --glass-fill-nested | tokens.css | … |
| --glow-sm | tokens.css | … |
| --ink-body | tokens.css | … |
| --ink-brand | tokens.css | … |
| --ink-disabled | tokens.css | … |
| --ink-inverse | tokens.css | … |
| --ink-muted | tokens.css | … |
| --line-glass | tokens.css | … |
| --line-soft | tokens.css | … |
| --r-lg | tokens.css | … |
| --r-md | tokens.css | … |
| --r-sm | tokens.css | … |
| --rgb-contact | tokens.css | … |
| --surface-solid | tokens.css | … |
| --table-cell-pad | tokens.css | … |
| --table-head-fill | tokens.css | … |
| --table-head-hover | tokens.css | … |
| --table-head-ink | tokens.css | … |
| --table-head-pad | tokens.css | … |
| --table-head-press | tokens.css | … |
| --table-head-rule | tokens.css | … |
| --table-row-hover | tokens.css | … |
| --table-row-line | tokens.css | … |
| --text-caption | tokens.css | … |
| --text-small | tokens.css | … |
| --wash-subtle | tokens.css | … |
Accessibility
- A nav labelled "Pagination"; the current page button has aria-current="page"; every button is named "Page n".
- Previous and next disable at the ends rather than disappearing, so the layout never jumps.
- The summary is a polite live region, so a page change is announced.
Do and don't
Do
- Reset to page one when a filter or sort changes.
- Keep it centred under the list it pages.
Don't
- Don't left-align the page buttons.
- Don't use infinite scroll for records people need to find again.
For AI agents
This page as markdown, rendered from the same registry entry. Point an agent at it (or add .md to this page's URL), or at /llms.txt for the index.
Open pagination.mdRelated: table, filter-bar