# Pagination

Page numbers with previous and next, from a page count or composed from parts.

```ehtml Example
import { Pagination } from "@elements/ui/pagination";

<Pagination page={state.page} total={20} />

<Pagination page={current} total={20} href={(p) => `/orders?page=${p}`} />
```

## Parts

| Part | What it is |
|---|---|
| `Pagination` | The nav landmark. With total it renders the whole control; without, its slot. |
| `PaginationContent` | The list of items. |
| `PaginationItem` | One list item. |
| `PaginationLink` | A page link. active marks the current page. |
| `PaginationPrevious` | Link to the previous page: a chevron and text. |
| `PaginationNext` | Link to the next page: text and a chevron. |
| `PaginationEllipsis` | Marks skipped pages; reads as "More pages". |

## Attributes

### Pagination

| Attribute | Type | Default | Description |
|---|---|---|---|
| `page` | `number` (two-way) | `1` | The current page, from startValue (1). Shown within startValue..total when it falls outside, as after total shrinks. |
| `total` | `number \| undefined` | `undefined` | The page count. 0 (no results) keeps Previous and Next, disabled, so the pager holds its place. Omitted renders the slot for a composed pagination. |
| `siblings` | `number` | `1` | Pages shown either side of the current one. |
| `boundaries` | `number` | `1` | Pages kept at each end. |
| `href` | `(page: number) => string` | `undefined` | Renders links with these targets. Without it the pages are buttons. |
| `controls` | `boolean` | `true` | Show Previous and Next. |
| `numbers` | `boolean` | `true` | Show page numbers. false shows "Page N of M" between the controls. |
| `edges` | `boolean` | `false` | Show First and Last. |
| `startValue` | `number` | `1` | The first page number: pages run from startValue to total. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Control size. |
| `variant` | `"text" \| "outlined"` | `"text"` | outlined: a border on every page and control; the current page takes the accent border. |
| `color` | `"standard" \| "primary" \| "secondary"` | `"standard"` | primary or secondary fills the current page with that button color. |
| `shape` | `"rounded" \| "circular"` | `"rounded"` | circular: round pages and controls. |
| `layout` | `"default" \| "responsive"` | `"default"` | responsive: in a narrow container, Page X of Y (statusText) replaces the page numbers. |
| `label` | `string` | `"Pagination"` | aria-label of the nav. |
| `previousText` | `string` | `"Previous"` | Previous control text. |
| `nextText` | `string` | `"Next"` | Next control text. |
| `getItemLabel` | `(kind: "first" \| "previous" \| "next" \| "last" \| "page", page: number) => string` | `undefined` | The aria-label of each control and page, for translation. page is the page the item goes to. Without it, English labels; translated control text with no label is the control's name. |
| `statusText` | `(page: number, total: number) => string` | `Page N of M` | The status between the controls when numbers is false, for translation. |
| `disabled` | `boolean` | `false` | Turns off every page and control: aria-disabled, no href, presses ignored. |
| `hideWithOnePage` | `boolean` | `false` | Renders nothing when total is 1, so a one-page list shows no pager. |
| `onPageChange` | `(page: number) => void` | `() => {}` | Called when the user changes the page. Not called for changes the caller makes. |
| `class` | `string` | `""` | Extra classes. Every part takes class. |

### PaginationLink

| Attribute | Type | Default | Description |
|---|---|---|---|
| `href` | `string` | `""` | The page's URL. Also on PaginationPrevious and PaginationNext. |
| `active` | `boolean` | `false` | The current page: outline look, aria-current="page". |
| `size` | `"sm" \| "md" \| "icon"` | `"icon"` | icon is a square for a number; md and sm fit text. |
| `disabled` | `boolean` | `false` | No href, aria-disabled, clicks ignored. Also on PaginationPrevious and PaginationNext. |
| `attrs` | `Record<string, string \| number \| boolean \| undefined>` | `{}` | Other attributes for the anchor. Also on PaginationPrevious and PaginationNext. |
| `onclick` | `(e: MouseEvent) => void` | `() => {}` | Click handler. Also on PaginationPrevious and PaginationNext. |

### PaginationPrevious

| Attribute | Type | Default | Description |
|---|---|---|---|
| `text` | `string` | `"Previous" / "Next"` | The control text, for translation. Also on PaginationNext. |
| `label` | `string` | `""` | The aria-label. Empty: "Go to previous page" for the English text, or the text itself once it is translated. Also on PaginationNext. |

## Slots

| Slot | Part | Content |
|---|---|---|
| `default` | `Pagination` | A PaginationContent, when total is 0. |
| `first-icon` | `Pagination` | An Icon that replaces First's chevrons. Also previous-icon, next-icon and last-icon. |
| `dots-icon` | `Pagination` | An Icon that replaces the ellipsis in every gap. |
| `default` | `PaginationContent` | PaginationItems. |
| `default` | `PaginationLink` | The page number. |

## Keyboard

| Keys | Action |
|---|---|
| `Tab` | Moves through the controls and pages. |
| `Enter` | Follows a link or presses a button. |
| `Space` | Presses a button. |

## Data attributes

| Attribute | Values | On |
|---|---|---|
| `data-active` | present on the current page | page link |
| `data-disabled` | present at the ends, or on everything when disabled | controls |
| `data-disabled` | present when disabled | Pagination |

## Accessibility

- A nav landmark labelled Pagination around a list.
- The current page has aria-current="page"; each page button is labelled "Page N".
- Previous, Next, First and Last are labelled ("Go to next page"); at the ends they are aria-disabled and keep focus instead of dropping it.
- Translated control text with no label becomes the control's name, so what is read matches what is shown; getItemLabel translates every label.
- Ellipses are hidden from assistive tech; the composed part says "More pages".

## See also

- [Accordion](accordion): A stack of headings that each show and hide a panel, one or several at a time.
- [Collapsible](collapsible): A trigger that shows and hides a region, with its height animated.
- [Tabs](tabs): Layered panels, one shown at a time, chosen from a list of tabs.
- [Breadcrumb](breadcrumb): The path to the current page as a trail of links, composed from parts or built from a list.
- [Tree](tree): A hierarchical list that opens with the arrow keys, selects one node or many, and loads children on demand.