# 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

- 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 | Default | 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[]` | `[10, 15, 20, 100]` | Choices in the results-per-page select. The current `pageSize` is always added. |
| `onPageSizeChange` | `(pageSize: number) => void` |  | Called with the new page size. Shows the select when set. |
| `hasFirstLast` | `boolean` | `true` | Shows the first and last page buttons. |
| `step` | `number` | `1` | Pages moved by previous and next. |
| `disabled` | `boolean` | `false` | Disables every control. |
| `label` | `string` | `'Pagination'` | The `nav` accessible name. |
| `rangeLabel` | `string` | `'{start}–{end} of {total}'` | The range text, with `{start}`, `{end}` and `{total}` filled in. |
| `pageSizeLabel` | `string` | `'Results per page'` | The select label and accessible name. |
| `pageSizeLabelCompact` | `string` | `'Show'` | The select label when the pagination is narrow. |
| `firstPageLabel` | `string` | `'First page'` | The first page button name. |
| `previousPageLabel` | `string` | `'Previous page'` | The previous page button name. |
| `nextPageLabel` | `string` | `'Next page'` | The next page button name. |
| `lastPageLabel` | `string` | `'Last page'` | The last page button name. |

## Examples

### A pager

```tsx
<Pagination page={page} totalItems={120} pageSize={10} onChange={setPage} />
```

## Related

- [Select](/docs/components/select.md)
