# Pagination

An accessible React pagination for Next.js and Tailwind CSS: page links with ellipses, Previous and Next, and a pill that slides to the current page.

Source: https://ui.fewtone.com/components/pagination

## Installation

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

## Usage

```tsx
import {
  getPaginationRange,
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@/components/ui/pagination"

// Pages as URLs (?page=3): links work in a server component
export function Pages({ page, pageCount }: { page: number; pageCount: number }) {
  return (
    <Pagination>
      <PaginationContent>
        <PaginationItem>
          <PaginationPrevious href={`?page=${page - 1}`} disabled={page === 1} />
        </PaginationItem>
        {getPaginationRange({ page, pageCount }).map((item, index) => (
          <PaginationItem key={item === "ellipsis" ? `ellipsis-${index}` : item}>
            {item === "ellipsis" ? (
              <PaginationEllipsis />
            ) : (
              <PaginationLink href={`?page=${item}`} isActive={item === page}>
                {item}
              </PaginationLink>
            )}
          </PaginationItem>
        ))}
        <PaginationItem>
          <PaginationNext href={`?page=${page + 1}`} disabled={page === pageCount} />
        </PaginationItem>
      </PaginationContent>
    </Pagination>
  )
}
```

## API reference

### Pagination

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | `"Pagination"` | The landmark's name. Give each one its own name when a page has two. |

### PaginationContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |

### PaginationItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |

### PaginationLink

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `isActive` | `boolean` | `false` | The current page: it gets the pill and aria-current="page". |
| `href` | `string` | – | The page's URL. Leave it out for a button that changes the page in place (use onClick). |
| `asChild` | `boolean` | `false` | Render the single child, for example Next.js Link, with the link's styles. When it's disabled, leave out the child's href too. |
| `disabled` | `boolean` | `false` | Marks it aria-disabled, fades it and stops it: onClick isn't called and a link loses its href. A button keeps its focus. |
| `size` | `"sm" \| "md" \| "lg" \| "icon" \| "icon-sm" \| "icon-lg"` | `"icon"` | Button's sizes. Page numbers are square icon sizes. |

### PaginationPrevious

| Prop | Type | Default | Description |
| --- | --- | --- | --- |

### PaginationNext

| Prop | Type | Default | Description |
| --- | --- | --- | --- |

### PaginationEllipsis

| Prop | Type | Default | Description |
| --- | --- | --- | --- |

### getPaginationRange

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `page` | `number` | – | The current page, from 1. |
| `pageCount` | `number` | – | How many pages there are. |
| `siblingCount` | `number` | `1` | Pages shown either side of the current one. |
| `boundaryCount` | `number` | `1` | Pages always shown at the start and the end. |

**When to use it:** Use Pagination below a list or table split into pages, such as search results or orders. Use hrefs when each page has its own URL, and buttons when the page changes in place. For a few views of the same data, use Switcher or Tabs instead.
**Built on:** Radix Slot.
**npm packages (installed by the CLI):** lucide-react@^1.52.0, motion@^14.0.0, radix-ui@^1.7.0.
**Installs these FewTone UI components with it:** `button`.

## Examples

### Ten pages

Pick a page and the pill slides to it. Ellipses stand for the pages in between, and the links keep their places as you move. Previous and Next turn off at the ends. Without an href, the links are buttons that change the page in place.

```tsx
"use client";

import {
  getPaginationRange,
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@/components/ui/pagination";
import { useState } from "react";

const pageCount = 10;

/*
 * Ten pages to click through. The pill slides to each new page; Previous and Next turn off at the ends.
 * Buttons, because the page changes in place; give the links an href (or asChild with your router's Link) to
 * move between URLs instead.
 */
export default function PaginationPages() {
  const [page, setPage] = useState(4);

  return (
    <Pagination>
      <PaginationContent>
        <PaginationItem>
          <PaginationPrevious disabled={page === 1} onClick={() => setPage((current) => current - 1)} />
        </PaginationItem>
        {getPaginationRange({ page, pageCount }).map((item, index) => (
          <PaginationItem key={item === "ellipsis" ? `ellipsis-${index}` : item}>
            {item === "ellipsis" ? (
              <PaginationEllipsis />
            ) : (
              <PaginationLink
                isActive={item === page}
                aria-label={`Page ${item}`}
                onClick={() => setPage(item)}
              >
                {item}
              </PaginationLink>
            )}
          </PaginationItem>
        ))}
        <PaginationItem>
          <PaginationNext disabled={page === pageCount} onClick={() => setPage((current) => current + 1)} />
        </PaginationItem>
      </PaginationContent>
    </Pagination>
  );
}
```

## Related

- [Table](https://ui.fewtone.com/components/table.md): An accessible React table for Next.js and Tailwind CSS: rows and columns with sortable headers, selectable rows and rows that glide when sorted.
- [Breadcrumb](https://ui.fewtone.com/components/breadcrumb.md): An accessible React breadcrumb for Next.js and Tailwind CSS: a trail of links whose levels animate as you move, with custom separators and a collapsed middle.
- [Switcher](https://ui.fewtone.com/components/switcher.md): An accessible React segmented control for Next.js: one choice from a few options, with a pill that slides to the one you pick.