# Pagination

Navigation for splitting content across multiple pages.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<DocsBaseSwitcher base="web" component="pagination" />

<ComponentPreview name="pagination" title="pagination.tsx">
<Component />
</ComponentPreview>

Pagination splits long content into pages. It composes standard links so navigation works with keyboard, screen readers, and browser history.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add pagination
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the base button:
</Step>

```bash
npx frakment add button
```

<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="pagination" title="components/ui/pagination.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx title="pagination.tsx"
import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@/components/ui/pagination";
```

```tsx
<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious href="#" />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="#">1</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationNext href="#" />
    </PaginationItem>
  </PaginationContent>
</Pagination>
```

## Examples [#examples]

### Simple [#simple]

Show every page number without an ellipsis.

<ComponentPreview name="pagination-simple" title="pagination-simple.tsx" src="examples/pagination-simple.tsx">
<a />
</ComponentPreview>

### Icons only [#icons-only]

Pair with a `Select` for page size, keeping the controls minimal.

<ComponentPreview name="pagination-icons-only" title="pagination-icons-only.tsx" src="examples/pagination-icons-only.tsx" previewClassName="h-auto py-8">
<h />
</ComponentPreview>

## Composition [#composition]

```text
Pagination
└── PaginationContent
    ├── PaginationItem
    ├── PaginationPrevious
    ├── PaginationNext
    └── PaginationEllipsis
```

## In Context [#in-context]

### Table footer [#table-footer]

<ComponentPreview name="pagination-table-footer" title="pagination-table-footer.tsx" src="examples/pagination-table-footer.tsx">
<d />
</ComponentPreview>

## API Reference [#api-reference]

### PaginationLink [#paginationlink]

<PropsTable rows={[{"name":"href","type":"string","description":"Destination URL."},{"name":"isActive","type":"boolean","defaultValue":"false","description":"Mark the link as the current page; sets aria-current."},{"name":"size","type":"sm | default | lg | icon","defaultValue":"icon","description":"Button size."}]} />

### Other parts [#other-parts]

All other parts extend `React.ComponentProps<"div">` (or `<a>` for `PaginationLink` and `PaginationPrevious` / `PaginationNext`).

## Accessibility [#accessibility]

- Uses `<nav>` with `aria-label="pagination"` for landmark navigation.
- Active page sets `aria-current="page"`.
- Previous and Next set `aria-label="Go to previous page"` and `aria-label="Go to next page"`.

## Best Practices [#best-practices]

- **Hide when total is one page.** Pagination with a single page is noise.
- **Show first, last, current, and neighbors.** Skip the middle with an ellipsis.
- **Keep page size in the URL.** Deep links and back button should work.
- **Use pagination, not infinite scroll, for tables.** Users need to jump around.