# Pagination

Page navigation with Prev/Next and numbered pages, or a simple "Page X of Y" mode.

- Category: Core Elements
- Page: https://wunderui.com/components/pagination
- Tier: Free

## Install

```bash
npx wunderui-cli add pagination
```

## Import

```tsx
import { Pagination, PaginationCurrentStyle, PaginationJump, PaginationJumpProps, PaginationPageSize, PaginationPageSizeProps, PaginationProps, PaginationShape, PaginationSimple, PaginationSimpleProps, PaginationSummary, PaginationSummaryProps } from "@/components/ui/pagination"
```

## Minimal usage

Then use it:

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

export function Invoices() {
  const [page, setPage] = useState(1)

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

Expected result: You see a disabled Prev button, pages 1 and 2, an ellipsis, page 12 and Next, with page 1 filled. Click 2 or Next to move the current page.

## Usage

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

export function Example() {
  const [page, setPage] = useState(5)
  return (
    <Pagination page={page} pageCount={12} onPageChange={setPage} />
  )
}
```

## When to use

### Use Pagination for

- Long tables and lists where people need to reach a specific page, such as invoices or members
- Search results, where position matters and people go back to a result they saw
- Server-side data, where every page is its own request

### Use something else

- [Tabs](https://wunderui.com/components/tabs) for peer views of one object, not pages of one list
- [Breadcrumb](https://wunderui.com/components/breadcrumb) for the path of a page inside the product
- [Carousel](https://wunderui.com/components/carousel) for a few slides or cards that people move through one at a time

## Keyboard

Every control is a native button, field or select, so the browser provides focus and activation.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous enabled button. A disabled Prev or Next and the ellipsis are skipped. |
| `Enter` or `Space` | Goes to the focused page, or one page back or forward from Prev and Next, or to the first or last page from the edge buttons. |
| `Enter` | In the jump field: goes to the typed page. A number outside 1 to `pageCount`, or no whole number, shows an error and stays where it is. It does not submit a form around the pager. |
| `ArrowDown` or `ArrowUp` | In the open page size menu: moves between the sizes. Enter or Space on the closed select opens the menu, Enter chooses the highlighted size and Escape closes it. |

## Behavior

What the pager does with state, the page list, the edges and motion.

- **Controlled:** Pagination keeps no state: the page comes from you, and every click reports the new number. Nothing changes until you set the page.
- **Which pages show:** The first page, the last page and the current page with one neighbour each side always show, so the row holds at most seven items. Gaps fold into an ellipsis, which can stand for a single page.
- **Edges:** Prev and Next are disabled on the first and last page: they keep their place, drop to 40% opacity and are skipped by Tab. The edge buttons follow the same rule.
- **Current page:** The current page stays a button, so choosing it again reports the same number. Hover tints a page with the page background and pressed with the subtle one; the current page keeps its own fill.
- **Narrow screens:** Below 640 px Prev and Next show only the arrow. The row never wraps and is about 340 px wide on a phone (412 px with edge buttons), so in a narrower space allow wrapping or use PaginationSimple.
- **Summary states:** Loading shows a skeleton and announces Loading results. Error is an alert saying the count could not load, with a Retry button if you set a retry handler, and a total of 0 reads No results.
- **Jump errors:** The error text of PaginationJump sits under the row without making it taller, so a form around it does not move. The input stays marked invalid until the next edit.
- **Numbers and direction:** Counts use the English format with a comma, such as 1,248. The chevrons turn 180 degrees in right-to-left layouts.
- **Motion:** Nothing slides: the current page changes in place. Page buttons change colour at the base speed; Prev, Next and the edge buttons a little faster.
- **Reduced motion:** There is no movement to remove, so reduced motion changes nothing. The colour changes are short fades and stay.

## Anatomy

- `Pagination`: A nav named Pagination with Prev and Next around numbered page buttons. You hold the page and change it in the page change handler; options are shape, current style and first and last buttons.
- `Edge buttons`: The first-page and last-page buttons at the two ends, shown with the edges option. Each is an icon button named First page or Last page.
- `Prev and Next`: Text buttons with a chevron: Prev is disabled on the first page and Next on the last. Below 640 px the text hides and the chevron stays, and screen readers still read the text.
- `Page button`: A numbered button that goes to its page. The row always shows the first page, the last page and the pages around the current one.
- `Current page`: The page you are on, marked as the current page. Primary fills it with the brand colour, subtle sets it on a quiet surface.
- `Ellipsis`: Stands for the pages that are folded away. It is plain text, not a button.
- `PaginationSimple`: The compact form: Previous and Next with a Page X of Y label between them, for narrow spaces. It takes the same shape.
- `PaginationSummary`: The count line: a range of a total (21 to 30 of 248), the total alone, a range without a total, a loading skeleton, or an error with a Retry button.
- `PaginationPageSize`: A labelled select for the number of rows per page. Its label is the accessible name of the select.
- `PaginationJump`: A labelled number field with a Go button. Enter or Go jumps to the page; a value outside 1 to the page count shows an error under the row.
- `Last`

## Best practices

### Do

- Keep the page in state and load the matching rows in the page change handler. Pages count from 1, and the page count is the total number of pages.
- Show where people are with PaginationSummary next to the pager, such as 21 to 30 of 248. When the total is unknown, leave it out and it says Showing 21 to 30.
- Reset the page to 1 when the page size, a filter or a search changes. Otherwise people can land on a page that no longer exists.
- Use PaginationSimple where only Previous and Next fit, such as a narrow card or a phone, and keep the count in PaginationSummary above the list.

### Don't

- Don't build page buttons by hand. Pagination already disables Prev on the first page and Next on the last, and marks the current page.
- Don't show a pager for one page. With a page count of 1 it shows a lone 1; hide it instead.
- Don't use Pagination for a feed that grows as people read. A list that appends more rows needs a Load more button or an infinite list, not pages.
- Don't let the page leave the range 1 to the page count. Pagination does not clamp it, so a stale page shows a row with no current number.

## API reference

### Pagination

| Prop | Type | Default | Description |
|---|---|---|---|
| onPageChange* | (page: number) => void |  | Called with the page the person chose: a number, or one before or after the current page from Prev and Next. |
| page* | number |  | The current page, counting from 1. It is a controlled value: update it in `onPageChange`. |
| pageCount* | number |  | The total number of pages. The last button and the end of the page list follow it. |
| className | string |  | Extra classes for the `<nav>`, for example `flex-wrap justify-center` on a narrow container. |
| currentStyle | "primary" \| "subtle" | "primary" | How the current page is drawn: `primary` fills it with the brand colour and is the default, `subtle` marks it with a quiet surface. |
| shape | "rounded" \| "pill" | "rounded" | `rounded` gives the buttons 8 px corners and is the default; `pill` rounds every button fully. |
| showEdges | boolean | false | Adds a first-page and a last-page button at the two ends of the row. |

### PaginationJump

| Prop | Type | Default | Description |
|---|---|---|---|
| onPageChange* | (page: number) => void |  | Called with a valid page (a whole number from 1 to `pageCount`). |
| pageCount* | number |  | The total number of pages. A typed page must be a whole number from 1 to this value. |
| buttonLabel | string | "Go" | Text of the button. Default "Go". |
| className | string |  | Extra classes for the row that holds the label, the field and the button. |
| disabled | boolean |  | Disables the field and the button. |
| label | string | "Go to page" | Visible label. Default "Go to page". |

### PaginationPageSize

| Prop | Type | Default | Description |
|---|---|---|---|
| onValueChange* | (value: number) => void |  | Called with the number of rows the person chose. Reset the page to 1 here. |
| value* | number |  | Current page size. |
| className | string |  | Extra classes for the row that holds the label and the select. |
| disabled | boolean |  | Disables the select, for example while a page loads. |
| label | string | "Rows per page" | Visible label. Default "Rows per page". |
| options | number[] | [10, 25, 50, 100] | Choices in the menu. Default 10, 25, 50, 100. |

### PaginationSimple

| Prop | Type | Default | Description |
|---|---|---|---|
| onPageChange* | (page: number) => void |  | Called with the previous or the next page when a button is pressed. |
| page* | number |  | The current page, counting from 1. It is shown in the `Page X of Y` label. |
| pageCount* | number |  | The total number of pages, shown as the Y of the label. Next is disabled on the last page. |
| className | string |  | Extra classes for the `<nav>`. The row spreads Previous, the label and Next across its width. |
| shape | "rounded" \| "pill" | "rounded" | `rounded` gives both buttons 8 px corners and is the default; `pill` rounds them fully. |

### PaginationSummary

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string |  | Extra classes for the text, the skeleton or the error row. |
| errorMessage | React.ReactNode |  | Shown instead of the default message while `status="error"`. |
| itemCount | number |  | Rows on the current page, for an unknown total or a short last page. Defaults to `pageSize`. |
| noun | string | "result" | Singular noun for the total, "result" in "248 results". |
| nounPlural | string |  | Plural noun, defaults to `noun` + "s". |
| onRetry | () => void |  | Makes the error state show a "Retry" button. |
| page | number |  | Current page, 1-based. Together with `pageSize` it gives the range "1–10". |
| pageSize | number |  | Rows per page. |
| status | "ready" \| "loading" \| "error" | "ready" | "loading" shows a skeleton, "error" says the count failed and offers a retry. |
| total | number |  | Total number of rows. Leave it out when the total is not known. |

## Examples

### Layout: numbered pages, first and last buttons, or Page X of Y

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

export function Example() {
  const [page, setPage] = useState(5)
  return (
    <Pagination page={page} pageCount={12} onPageChange={setPage} />
  )
}
```

### Position: first page, middle and last page

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

export function Example() {
  const [page, setPage] = useState(1)
  return (
    <Pagination page={page} pageCount={12} onPageChange={setPage} />
  )
}
```

### Summary: range, total, unknown total, loading and error

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

export function Example() {
  return (
    <PaginationSummary page={3} pageSize={10} total={248} />
  )
}
```

### Controls: page size and jump to page

```tsx
import { useState } from "react"
import { PaginationPageSize } from "@/components/ui/pagination"

export function Example() {
  const [pageSize, setPageSize] = useState(10)
  return (
    <div className="flex flex-col items-center gap-3">
      <PaginationPageSize value={pageSize} onValueChange={setPageSize} />
      <p className="text-sm text-text-secondary">Showing {pageSize} invoices per page</p>
    </div>
  )
}
```

## In context

### Invoices: a table footer with count, page size and pages

The footer holds the range, the page size and the pager. Choosing another page size starts again at page 1, and the table keeps the height of eight rows.

```tsx
import { useState } from "react"
import {
  Pagination,
  PaginationPageSize,
  PaginationSummary,
} from "@/components/ui/pagination"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

const CUSTOMERS = ["Nora Lindgren", "Daniel Okafor", "Priya Raman", "Tomás Ferreira", "Maya Kessler"]

// 48 invoices, newest first.
const INVOICES = Array.from({ length: 48 }, (_, i) => ({
  id: `INV-${1048 - i}`,
  customer: CUSTOMERS[i % CUSTOMERS.length],
  amount: `$${(1240 + ((i * 7919) % 8600)).toLocaleString("en-US")}.00`,
}))

export function Example() {
  const [page, setPage] = useState(1)
  const [pageSize, setPageSize] = useState(5)
  const pageCount = Math.ceil(INVOICES.length / pageSize)
  const rows = INVOICES.slice((page - 1) * pageSize, page * pageSize)

  return (
    <div className="flex w-full max-w-2xl flex-col overflow-hidden rounded-xl border border-border bg-card">
      <Table>
        <TableHeader>
          <TableRow>
            <TableHead>Invoice</TableHead>
            <TableHead>Customer</TableHead>
            <TableHead className="text-right">Amount</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {rows.map((invoice) => (
            <TableRow key={invoice.id}>
              <TableCell className="font-medium">{invoice.id}</TableCell>
              <TableCell>{invoice.customer}</TableCell>
              <TableCell className="text-right tabular-nums">{invoice.amount}</TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
      <div className="flex flex-wrap items-center justify-between gap-x-6 gap-y-3 border-t border-border px-4 py-3">
        <div className="flex flex-wrap items-center gap-x-6 gap-y-2">
          <PaginationSummary page={page} pageSize={pageSize} total={INVOICES.length} />
          <PaginationPageSize
            value={pageSize}
            options={[5, 8]}
            onValueChange={(size) => {
              setPageSize(size)
              setPage(1)
            }}
          />
        </div>
        <Pagination page={page} pageCount={pageCount} onPageChange={setPage} />
      </div>
    </div>
  )
}
```

### Search results: the simple pager under a short list

Where only Previous and Next fit, PaginationSimple keeps the page count between them. The summary above the list says which results are on screen.

```tsx
import { useState } from "react"
import { PaginationSimple, PaginationSummary } from "@/components/ui/pagination"

const RESULTS = [
  { title: "Change your billing plan", text: "Switch between Team and Business at any time. The change applies immediately." },
  { title: "Update your payment method", text: "Add a new card and make it the default for the next invoice." },
  { title: "Download an invoice", text: "Every invoice is a PDF in Billing, listed from the newest." },
  { title: "Add a team member", text: "Invite people by email and choose a role for each of them." },
  { title: "Reset your password", text: "Open Security in your account settings and choose Reset password." },
  { title: "Turn on two-factor authentication", text: "Protect your account with a code from an authenticator app." },
  // ...six more
]

const PAGE_SIZE = 3

export function Example() {
  const [page, setPage] = useState(1)
  const pageCount = Math.ceil(RESULTS.length / PAGE_SIZE)
  const results = RESULTS.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE)

  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <PaginationSummary page={page} pageSize={PAGE_SIZE} total={RESULTS.length} />
      <ul className="flex flex-col gap-3">
        {results.map((result) => (
          <li key={result.title} className="flex flex-col gap-1">
            <span className="text-sm font-medium text-text-link">{result.title}</span>
            <span className="text-sm text-text-secondary">{result.text}</span>
          </li>
        ))}
      </ul>
      <PaginationSimple page={page} pageCount={pageCount} onPageChange={setPage} />
    </div>
  )
}
```

### Activity feed: ready, loading and failed

The summary changes with the request. While loading it shows a skeleton and placeholder rows; after a failure it offers Retry in place of the pager.

```tsx
import { useState } from "react"
import { Pagination, PaginationSummary } from "@/components/ui/pagination"

const PEOPLE = ["Nora Lindgren", "Daniel Okafor", "Priya Raman", "Tomás Ferreira", "Maya Kessler"]
const ACTIONS = ["changed the billing plan", "invited a member", "renamed the workspace", "exported the invoices"]

// 20 entries, newest first.
const ACTIVITY = Array.from({ length: 20 }, (_, i) => ({
  who: PEOPLE[i % PEOPLE.length],
  what: ACTIONS[i % ACTIONS.length],
  when: `${(i + 1) * 3} min ago`,
}))

const PAGE_SIZE = 4

export function Example() {
  const [page, setPage] = useState(1)
  const pageCount = Math.ceil(ACTIVITY.length / PAGE_SIZE)
  const items = ACTIVITY.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE)

  return (
    <div className="flex w-full max-w-md flex-col gap-4">
      <PaginationSummary page={page} pageSize={PAGE_SIZE} total={ACTIVITY.length} />
      <ul className="flex flex-col gap-3">
        {items.map((item) => (
          <li key={item.when} className="flex items-baseline justify-between gap-4 text-sm">
            <span className="text-foreground">
              <span className="font-medium">{item.who}</span> {item.what}
            </span>
            <span className="text-text-tertiary">{item.when}</span>
          </li>
        ))}
      </ul>
      <Pagination page={page} pageCount={pageCount} onPageChange={setPage} />
    </div>
  )
}
```

## For AI agents

`get_component("pagination")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
