Pagination
Page controls for a paged list: the item range, an optional results-per-page select, first, previous, next and last buttons, and the page over the total. Pages start at 1.
Use for
- moving between pages of a table or list
- choosing how many results show per page
Practices
| Guidance | Practice |
|---|---|
| Do | Pass localized strings for every label. The defaults are English. |
| Do | Pass onPageSizeChange to show the results-per-page select. It is hidden without one. |
| Don’t | Clamp the page yourself. onChange gets a page between 1 and the last page. |
API reference
Pagination
A nav labelled by label. Out-of-range page values render as the nearest valid page.
Slot: cl-pagination
| Prop | Type | Description |
|---|---|---|
page | number | The current page. |
totalItems | number | The item count across all pages. |
pageSize | number | Items per page. |
onChange | (page: number) => void | Called with the page the user asked for. |
pageSizeOptions | number[] | Choices in the results-per-page select. The current pageSize is always added.Default: [10, 15, 20, 100] |
onPageSizeChange | (pageSize: number) => void | Called with the new page size. Shows the select when set. |
hasFirstLast | boolean | Shows the first and last page buttons.Default: true |
step | number | Pages moved by previous and next.Default: 1 |
disabled | boolean | Disables every control.Default: false |
label | string | The nav accessible name.Default: 'Pagination' |
rangeLabel | string | The range text, with {start}, {end} and {total} filled in.Default: '{start}–{end} of {total}' |
pageSizeLabel | string | The select label and accessible name.Default: 'Results per page' |
pageSizeLabelCompact | string | The select label when the pagination is narrow.Default: 'Show' |
firstPageLabel | string | The first page button name.Default: 'First page' |
previousPageLabel | string | The previous page button name.Default: 'Previous page' |
nextPageLabel | string | The next page button name.Default: 'Next page' |
lastPageLabel | string | The last page button name.Default: 'Last page' |
Examples
A pager
<Pagination page={page} totalItems={120} pageSize={10} onChange={setPage} />