Pagination
Page-by-page navigation.
Usage
Give Root the count of items and perPage; it works out the pages. page is bindable.
Why you render the pages
Root does not emit buttons — it hands you a pages array through a snippet
and you render them. That indirection looks like extra work and buys something real: Bits owns the
page range, the ellipsis logic and the keyboard navigation, while the markup stays entirely yours.
Each entry is either type: 'page' — pass it to Pagination.Page — or type: 'ellipsis', which
you render however you like. Use p.key as the each key.
Accessibility
Wrap the whole thing in <nav aria-label="Pagination">. Bits
gives the buttons their roles and marks the active page with data-selected and aria-label, so the current
page is announced rather than only coloured differently.
Prev and Next are disabled at the ends automatically. If you render them as arrows with no
text, give each an aria-label — an unlabelled arrow button is announced
as nothing at all.
Props
Pagination.Root
| Prop | Type | Default |
|---|---|---|
page Current page number. Bindable. | number | 1 |
class Extra classes merged onto the root. | string | — |
child bits-ui | Snippet<[PaginationSnippetProps & { props: Record<string, unknown>; }]> | undefined | — |
children bits-ui | Snippet<[PaginationSnippetProps]> | undefined | — |
count required bits-ui The total number of items to be paginated. | number | — |
id bits-ui | string | undefined | — |
loop bits-ui Whether keyboard navigation should loop back to the first or last page trigger when reaching either end. | boolean | undefined | false |
onPageChange bits-ui A callback function called when the page changes. | OnChangeFn<number> | undefined | — |
orientation bits-ui The orientation of the pagination component. Used to determine how keyboard navigation should work between pages. | "horizontal" | "vertical" | undefined | "horizontal" |
perPage bits-ui The number of items per page. | number | undefined | 1 |
ref bits-ui | HTMLElement | null | undefined | — |
siblingCount bits-ui The number of visible items before and after the current page. | number | undefined | 1 |
Page takes the page object from the snippet. PrevButton and NextButton take class plus the native button attributes.
| Prop | Type | Default |
|---|---|---|
class Extra classes merged onto the page button. | string | — |
child bits-ui | Snippet<[{ props: Record<string, unknown>; }]> | undefined | — |
children bits-ui | Snippet<[]> | undefined | — |
id bits-ui | string | undefined | — |
page required bits-ui | Page | — |
ref bits-ui | HTMLElement | null | undefined | — |