---
title: Pagination (React) - USWDS + Tailwind
description: Help visitors move through paginated content with bounded and
  unbounded pagination patterns.
---

# Pagination

Help visitors move through paginated content with bounded and unbounded pagination patterns.

## Examples

### Bounded

```tsx
import { Pagination } from '@uswds-tailwind/react/pagination'

export default function PaginationBoundedDemo() {
  return (
    <Pagination.Root currentPage={6} pageCount={8}>
      <Pagination.List>
        {({ pages }) => (
          <>
            <Pagination.PrevTrigger />
            {pages.map((page, index) =>
              page.type === 'page'
                ? <Pagination.Item key={page.value} value={page.value} />
                : <Pagination.Ellipsis key={`ellipsis-${index}`} />,
            )}
            <Pagination.NextTrigger />
          </>
        )}
      </Pagination.List>
    </Pagination.Root>
  )
}
```

#### Pages shortcut

`Pagination.Pages` renders a `Pagination.Item` for each visible page and a `Pagination.Ellipsis` for each gap. Inside `Pagination.List`, this:

```tsx
<Pagination.List>
  <Pagination.PrevTrigger />
  <Pagination.Pages />
  <Pagination.NextTrigger />
</Pagination.List>
```

is shorthand for the render function used in the full example above:

```tsx
<Pagination.List>
  {({ pages }) => (
    <>
      <Pagination.PrevTrigger />
      {pages.map((page, index) =>
        page.type === 'page'
          ? <Pagination.Item key={page.value} value={page.value} />
          : <Pagination.Ellipsis key={'ellipsis-' + index} />,
      )}
      <Pagination.NextTrigger />
    </>
  )}
</Pagination.List>
```

### Unbounded

```tsx
import { Pagination } from '@uswds-tailwind/react/pagination'

export default function PaginationUnboundedDemo() {
  return (
    <Pagination.Root currentPage={6}>
      <Pagination.List>
        <Pagination.PrevTrigger />
        <Pagination.Pages />
        <Pagination.NextTrigger />
      </Pagination.List>
    </Pagination.Root>
  )
}
```

## Component API

Place List inside Root. Use PrevTrigger, NextTrigger, Item, Ellipsis, or the Pages shortcut to build page navigation.

### Root `<nav>`

Owns the current page.

| Prop | Type | Default | Description |
| - | - | - | - |
| `currentPage` | `number` | `1` | Initial page or controlled page when onPageChange is supplied. |
| `pageCount` | `number` | `—` | Total page count. |
| `onPageChange` | `(page: number) => void` | `—` | Receives page changes; supply currentPage to control the state. |

### List `<ul>`

Contains navigation items.

| Prop | Type | Description |
| - | - | - |
| `children` | `ReactNode \| ({ pages: PageSlot[] }) => ReactNode` | Renders items directly or from computed page slots. |

### PrevTrigger `<button>`

Moves to the previous page.

### NextTrigger `<button>`

Moves to the next page.

### Item `<li>`

Wraps a button by default. Button props and page-state attributes apply to that inner button; render can replace it with a custom control.

| Prop | Type | Description |
| - | - | - |
| `value` | `number (required)` | Page number. |
| `render` | `(props: PaginationItemRenderProps) => ReactNode` | Renders a custom page control. |

### Ellipsis `<li>`

Marks a gap in the visible page sequence.

### Pages

Renders Item and Ellipsis parts from the computed page sequence.

| Prop | Type | Description |
| - | - | - |
| `render` | `PaginationItemProps["render"]` | Customizes the page controls. |
