# Pagination

> Pages of a long list: the current-page mark is thrown to the new number, and in a narrow container it becomes "3 of 12" with a number that rolls.

Pagination usually repaints the current number and wraps badly on phones. Here one mark is thrown to the new page with a slight overshoot, the window of numbers keeps its width as you move, and in a narrow container it becomes ‹ 3 of 12 › with the number rolling the way you moved. Pass hrefFor and pages become real links.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/pagination.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): `number-roll`, `ui-interaction-motion`
- Docs and live preview: https://hairlineui.com/ui/pagination
- Registry item (source): https://hairlineui.com/r/pagination.json

## Usage

```tsx
import { Pagination } from "@/components/ui/pagination";

<Pagination page={page} pageCount={12} onPageChange={setPage} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `page / defaultPage` | `number` | – | Current page (1-based). |
| `pageCount` | `number` | – | Total pages. |
| `onPageChange` | `(page: number) => void` | – | Called on change. |
| `siblings` | `number` | `1` | Pages either side of the current one. |
| `hrefFor` | `(page) => string` | – | Make pages links. |

## States

- **move**: The mark is thrown to the new page (420ms, slight overshoot).
- **narrow**: The number rolls the way you moved.

## What it handles

Pagination is either numbers or "3 of 12"; this one is both and picks by the room it has.

- **Moving mark**: One mark, thrown (420ms).
- **Smart window**: First, last, current ± siblings, with gaps.
- **Container aware**: Below 22rem it switches to a rolling "3 of 12".
- **Real links**: hrefFor makes anchors with client-side clicks.

## Replaces

pagination, page range logic

## Where it fits

- **Tables**: Under a list of customers or invoices.
- **Search results**: Linked pages that search engines can follow.
- **Galleries**: Pages of templates or photos.
- **Logs**: Paging through history.

## Notes

- A nav landmark; the current page has aria-current="page".
- Reduced motion: the mark moves at once.

License: MIT (https://hairlineui.com/license#components)