# Pager (goodtabs UI)

Page navigation with prev and next pills, numbered pages and an ellipsis for long ranges.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/pager.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/pager`

## Usage

```tsx
import { Pager } from "@/components/ui/pager"

const [page, setPage] = useState(1)

<Pager page={page} pageCount={12} onPageChange={setPage} />
<Pager variant="compact" page={page} pageCount={12} onPageChange={setPage} />
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| page | `number` |  | The current page, from 1. Clamped to the page count. |
| pageCount | `number` |  | Total number of pages. |
| onPageChange | `(page: number) => void` |  | Called with the page to go to. |
| siblingCount | `number` | `1` | Pages shown on each side of the current one. |
| showEdges | `boolean` | `true` | Always show the first and last page numbers. |
| variant | `"numbers" | "compact"` | `"numbers"` | compact drops the numbers for a mono "Page n of m" between the arrows. |

## When to use

- Under a table or list that is split into pages on the server
- When people need to jump to a specific page, not just the next one
- In a toolbar where only prev and next fit: use the compact variant

## When not to use

- For feeds that load more as you scroll: use a load more button instead
- For steps in a flow, which have an order and a finish
- When there is only one page: render nothing

## Notes for agents

- Controlled only: it never stores the page, so pass page and update it in onPageChange
- It takes a function, so the parent that renders it must be a client component
- The current page is bg-primary with aria-current; prev and next disable at the edges
- The row does not wrap; with many pages and a wide siblingCount, give it a scrolling box

Docs: https://ui.goodtabs.co/components/pager