All components (204)

Pagination

Navigation · Pagination · .amset-pagination

What it is and when to use it

The page controls of any list, not only the table: previous and next, the numbers with gaps ("1 … 8 9 10 11 12 … 14"), the count "11-20 of 137 invoices" and, if requested, first and last, direct jump and rows per page.

When to use it

Result lists that are traversed by pages and where it matters to know where you are (invoices, orders, customers).
total and size when it is known how many there are: the count and the pages appear. Only pages when the server says how many pages there are and not how many items.
skip from around twenty pages; ends when there are many and you often go to the start or the end.
shape="compact" where the numbers do not fit: "Page 2 of 5" between the two arrows.
label if there are two on the same screen ("Order pages", "Customer pages"): if both are called "Pagination", the reader cannot tell them apart.
itemNames with { singular, plural } so the count agrees: "1 of 1 invoice", "11-20 of 42 invoices".

When not to

Inside a Table: it already brings it with its pagination prop.
For lists that keep growing at the end: LoadMoreButton, which says how many have been loaded out of how many.
With thousands of rows that are to be traversed continuously: VirtualList.

Keyboard: Tab goes through the buttons; disabled ones (previous on the first page, next on the last) do not take focus. Enter or Space press them. If on reaching an end the button that had focus is turned off, focus moves to the current page (or, in the compact shape, to the other arrow) instead of getting lost. The direct jump is a form: the number is typed and "Go to" or Enter is pressed; a number out of range is clamped to the first or the last page.

Accessibility: it is a nav called "Pagination", or whatever label says. The count goes in a role="status", so the page change is announced. The current page carries aria-current="page" in addition to the filled button, each number is called "Page 7" and the "…" gaps are not read. Numbers are written according to the language ("1,240"). "Go to" is a real button, not only the Enter key: with a finger there is no Enter.

Context: it goes inside LocaleProvider (or AmsetProvider), which decides how numbers are written.

Fine-tuning: no variables of its own: adjust it with the classes amset-pagination, amset-pagination__number and amset-pagination__count. The buttons are Button and IconButton in sm size, so they also respond to --amset-button-*.

What it looks like

<Pagination page={pagina} total={240} size={25} onPageChange={setPagina} />

Props

Import it with import { Pagination } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`onPageChange`required	`(page: number) => void`	—
`page`required	`number`	—
`className`	`string`	Merged with the library classes; it does not replace them.
`disabled`	`boolean`	—
`ends`	`boolean`	First and last page buttons.
`itemNames`	`ItemNames`	What the thing being paginated is called, for the count.
`label`	`string`	Name of the navigation. By default "Pagination": with two on the same page, each its own ("Order pages"), or the reader confuses them.
`onPageSizeChange`	`(size: number) => void`	—
`pages`	`number`	When the server only says how many pages there are.
`renderPage`	`(page: number, state: { readonly current: boolean; }) => ReactNode`	Paints the content of each page's button (a number with a notification dot, a section name). The button is still called "Page N" for the screen reader. Only with `shape="full"`: the compact one has no buttons.
`shape`	`PaginationShape`	`full` draws the page numbers; `compact`, only previous and next.
`showCount`	`boolean`	"1-10 of 42 invoices". It needs the total.
`size`	`number`	—
`sizes`	`readonly number[]`	—
`skip`	`boolean`	Field to go straight to a page. Useful from twenty pages up.
`total`	`number`	How many items there are in total; the pages come from this and from `size`.
`window`	`number`	How many numbers are shown around the current one.

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

CSS variables

These CSS variables are how you adapt it. Declare them on the component's selector, not on :root: the stylesheet redeclares them in the rule itself, and a declaration on the same element always wins.

Variable	Default
`--amset-pagination-gap`	`var(--amset-space-3)`
`--amset-pagination-font`	`var(--amset-text-sm)`

How to change it

.amset-pagination {
  --amset-pagination-gap: ...;
  --amset-pagination-font: ...;
}

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: