# Pagination

> Source: https://design.nanatec.co.ke/components/pagination/
> A navigation control for paged data. It lives **beside** a table or list, never inside it. Controlled-by-attribute but self-updating: clicking moves the page (updating `page`) and emits `nana-page-change` so consumers can slice (client-side) or refetch (server-side).

A navigation control for paged data. It lives **beside** a table or list, never inside it. Controlled-by-attribute but self-updating: clicking moves the page (updating `page`) and emits `nana-page-change` so consumers can slice (client-side) or refetch (server-side).

## Preview

```html
<nana-pagination page="1" total-pages="10"></nana-pagination>
```

## Installation

```bash
npm install @nana-tec/ui-components
```

## Import

```js
import "@nana-tec/ui-components/pagination";
```

## Basic usage

```html
<nana-pagination page="1" total-pages="10"></nana-pagination>
```

## Layouts

The `layout` attribute switches between `numbered` (default), `compact`, and
`simple`.

```html
<nana-pagination page="4" total-pages="20" layout="numbered" show-first-last></nana-pagination>
<nana-pagination page="4" total-pages="20" layout="compact"></nana-pagination>
<nana-pagination page="4" total-pages="20" layout="simple"></nana-pagination>
```

## Variants

```html
<nana-pagination page="6" total-pages="64" variant="default"></nana-pagination>
<nana-pagination page="6" total-pages="64" variant="soft"></nana-pagination>
<nana-pagination page="6" total-pages="64" variant="filled"></nana-pagination>
<nana-pagination page="6" total-pages="64" variant="pill"></nana-pagination>
<nana-pagination page="6" total-pages="64" variant="ghost"></nana-pagination>
```

## Sizes

```html
<nana-pagination page="3" total-pages="10" size="sm" variant="soft"></nana-pagination>
<nana-pagination page="3" total-pages="10" size="md" variant="soft"></nana-pagination>
<nana-pagination page="3" total-pages="10" size="lg" variant="soft"></nana-pagination>
```

## API

## Events

| Event | Type | Description |
|---|---|---|
| `nana-page-change` | `CustomEvent` | detail: \{ page \} |
| `nana-page-size-change` | `CustomEvent` | detail: \{ pageSize \} |

## CSS Variables

| Variable | Default | Description |
|---|---|---|
| `--nana-pagination-radius` | — | Corner radius of the page controls |
| `--nana-pagination-active-bg` | — | Active page background (filled / pill) |
| `--nana-pagination-active-color` | — | Active page text colour (filled / pill) |

## CSS Parts

| Part | Description |
|---|---|
| `nav` | The controls container — every page-number and navigation button |
| `ellipsis` | The truncation gap (`…`) between page runs |

## Accessibility

<ul class="a11y-grid not-content">
  <li>Keyboard accessible</li>
  <li>Screen-reader labels</li>
  <li>Focus-visible states</li>
  <li>ARIA roles and states</li>
  <li>WCAG 2.2 AA contrast</li>
</ul>

## Related components

<ul class="related not-content">
  <li><a href="/components/breadcrumb/">Breadcrumb</a></li>
  <li><a href="/components/breadcrumb-item/">Breadcrumb Item</a></li>
  <li><a href="/components/menu/">Menu</a></li>
  <li><a href="/components/menu-item/">Menu Item</a></li>
  <li><a href="/components/menu-label/">Menu Label</a></li>
</ul>

## Storybook

See every state and prop interactively in Storybook: https://storybook.nanatec.co.ke/?path=/docs/components-pagination--docs