# Pagination

Moves between pages of a long list or table: Previous, the page numbers around the current one, Next. Pages are real links when they have a URL (getHref), or buttons that call onPageChange. They look like small Buttons: ghost, and secondary for the current page.

## Cách dùng

### Khi nào dùng

- Move between pages of a long list or table, with the total number of pages known.
- Lists whose pages have a URL, so a page can be shared and reloaded.

### Khi nào không dùng

- A short list. Show it whole.
- The steps of a flow.
- Sections of one page. Use Tabs.

## Ví dụ

### Links

Each page has a URL, so the pages are real links.

```tsx
<Pagination page={4} pageCount={12} getHref={pageHref} />
```

### Buttons

No URLs: the pages call onPageChange.

```tsx
<Pagination page={1} pageCount={5} onPageChange={goToPage} />
```

## Nên và không nên

### Nên

- Give pages a URL with getHref when the list has one, so a page can be shared and reloaded.
- Keep it under the list it pages, and move focus to the top of the list after a page change.
- Say how many results there are near the list, not only the page count.
- When the next page loads from the server, change page in a transition (useTransition) and keep the current rows on screen with Table pending, instead of blanking the list.

### Không nên

- Don't use it for the steps of a flow.
- Don't page a short list; show it whole.
- Don't change siblingCount between pages of one list; the links would jump.

## Props

| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
| --- | --- | --- | --- | --- |
| `page` | `number` |  |  | Set on Pagination. The current page, from 1. |
| `pageCount` | `number` |  |  | Set on Pagination. How many pages there are. |
| `onPageChange` | `function` |  |  | Set on Pagination. Called with the page to go to, when the pages are buttons. |
| `siblingCount` | `number` |  | `1` | Set on Pagination. Pages shown on each side of the current one. The first and last page always show. |
| `getHref` | `function` |  |  | Set on Pagination. Returns the URL of a page: (page) => `?page=${page}`. With it the pages are real links, so they open in a new tab and work without JavaScript. |
| `isActive` | `boolean` |  | `false` | Set on PaginationLink in your own layout. Marks the current page. |

## Cấu tạo

| Phần | Mô tả |
| --- | --- |
| `root` | Pagination: a nav named Pagination. With page and pageCount it draws everything below; with children it holds your own PaginationContent. |
| `content` | PaginationContent: the row of items, gap-xs, that wraps. |
| `item` | PaginationItem: one slot in the row. |
| `link` | PaginationLink: a page, an sm ghost Button at least as wide as it is tall, with tabular figures. The current page is secondary. |
| `step` | PaginationPrevious and PaginationNext: sm ghost Buttons with a 16px caret and the words Previous and Next. |
| `ellipsis` | PaginationEllipsis: Tabler DotsThree, 16px, in place of the pages left out. |
| `hitArea` | Transparent ::before on every link, never smaller than size-target-min. |

## Khả năng truy cập

Role: `navigation`

| Phím | Hành động |
| --- | --- |
| `Tab` | Moves through Previous, the pages and Next. |
| `Enter, Space` | Goes to that page (Space only on buttons). |

- The nav is named Pagination. Each page is named Page 3, and the current one carries aria-current="page".
- The current page stands out by its border and fill, not only by color.
- Previous on the first page and Next on the last are disabled: a button gets disabled, a link loses its href and gets aria-disabled.
- The ellipsis is decorative; the page numbers around it say where the gap is.
- Each page link keeps a size-target-min hit area.

## Cài đặt

```bash
npx shadcn add https://werewolf-ui.vercel.app/r/pagination.json
```

Lệnh này thêm luôn `styles/werewolf.css`, bộ token mà mọi component dùng, và các component khác mà nó cần. Import file đó một lần trong CSS gốc, ngay sau `@import "tailwindcss"`, với đường dẫn tính từ file CSS đó (từ `app/globals.css` là `@import "../styles/werewolf.css"`).