---
title: Pagination
description: Page navigation with composable page links, previous/next buttons, and ellipsis indicators
links:
  source: pagination/pagination.tsx
  styles: pagination.css
  storybook: Components/Navigation/Pagination
---

## Usage

```tsx
import { Pagination } from '@heroui/react';
```

<ComponentPreview
  name="pagination-basic"
/>

## Anatomy

```tsx
import { Pagination } from '@heroui/react';

export default () => (
  <Pagination>
    <Pagination.Summary>Showing 1-10 of 100 results</Pagination.Summary>
    <Pagination.Content>
      <Pagination.Item>
        <Pagination.Previous>
          <Pagination.PreviousIcon />
          <span>Previous</span>
        </Pagination.Previous>
      </Pagination.Item>
      <Pagination.Item>
        <Pagination.Link isActive>1</Pagination.Link>
      </Pagination.Item>
      <Pagination.Item>
        <Pagination.Ellipsis />
      </Pagination.Item>
      <Pagination.Item>
        <Pagination.Link>10</Pagination.Link>
      </Pagination.Item>
      <Pagination.Item>
        <Pagination.Next>
          <span>Next</span>
          <Pagination.NextIcon />
        </Pagination.Next>
      </Pagination.Item>
    </Pagination.Content>
  </Pagination>
);
```

## Examples

### Sizes

<ComponentPreview
  name="pagination-sizes"
/>

### Disabled

<ComponentPreview
  name="pagination-disabled"
/>

### Simple (Previous / Next)

<ComponentPreview
  name="pagination-simple-prev-next"
/>

### Controlled

<ComponentPreview
  name="pagination-controlled"
/>

### With Ellipsis

<ComponentPreview
  name="pagination-with-ellipsis"
/>

### With Summary

<ComponentPreview
  name="pagination-with-summary"
/>

### Custom Icons

You can replace the default chevron icons by passing custom children to `PreviousIcon` and `NextIcon`.

<ComponentPreview
  name="pagination-custom-icons"
/>

## Customization

### Tailwind CSS

<ComponentPreview name="pagination-custom-styles" />

### Global CSS

To customize the Pagination component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .pagination {
    @apply gap-8;
  }

  .pagination__link {
    @apply rounded-md;
  }

  .pagination__summary {
    @apply text-xs font-semibold;
  }
}
```

## Styling Reference

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The Pagination component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/pagination.css)):

#### Base & Layout Classes [!toc]
- `.pagination` - Root navigation container with flex layout
- `.pagination__summary` - Left-side info text container
- `.pagination__content` - Container for pagination items
- `.pagination__item` - Individual item wrapper
- `.pagination__link` - Page number button (ghost button style)
- `.pagination__link--nav` - Navigation button modifier (Previous/Next)
- `.pagination__ellipsis` - Ellipsis indicator

#### Size Classes [!toc]
- `.pagination--sm` - Small size variant
- `.pagination--md` - Medium size variant (default)
- `.pagination--lg` - Large size variant

### Interactive States

The component supports both CSS pseudo-classes and data attributes for flexibility:

- **Active page**: `[data-active="true"]` or `[aria-current="page"]`
- **Hover**: `:hover` or `[data-hovered="true"]`
- **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
- **Disabled**: `:disabled` or `[aria-disabled="true"]`
- **Pressed**: `:active` or `[data-pressed="true"]`

## API Reference

### Pagination

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the pagination items |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode` | - | Pagination parts (Summary, Content) |

### Pagination.Summary

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode` | - | Summary content (e.g., "Showing 1-10 of 120") |

### Pagination.Content

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode` | - | Pagination items |

### Pagination.Item

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode` | - | Item content (Link, Previous, Next, or Ellipsis) |

### Pagination.Link

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `isActive` | `boolean` | `false` | Whether this is the current page |
| `isDisabled` | `boolean` | `false` | Whether the link is disabled |
| `onPress` | `(e: PressEvent) => void` | - | Press handler (from React Aria) |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode` | - | Page number content |

### Pagination.Previous / Pagination.Next

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `isDisabled` | `boolean` | `false` | Whether the button is disabled |
| `onPress` | `(e: PressEvent) => void` | - | Press handler (from React Aria) |
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode` | - | Button content (compose with PreviousIcon/NextIcon) |

### Pagination.PreviousIcon / Pagination.NextIcon

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | - | Additional CSS classes |
| `children` | `ReactNode` | Default chevron SVG | Custom icon to replace the default chevron |

### Pagination.Ellipsis

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | - | Additional CSS classes |

## Note

Pagination buttons use `onPress` instead of `onClick`. The `onPress` handler from React Aria normalizes press behavior across pointer types and provides accessibility improvements out of the box.

## Accessibility

The Pagination component is built on [React Aria's Button](https://react-spectrum.adobe.com/react-aria/Button.html) primitive for all interactive elements, providing:

- Semantic `<nav>` element with `aria-label="pagination"` and `role="navigation"`
- Active page indicated via `aria-current="page"` on the current link
- Keyboard navigation via Tab key through all interactive elements
- Press events handled across mouse, touch, and keyboard interactions via React Aria
- Focus ring on keyboard navigation via `:focus-visible`
- Ellipsis marked with `aria-hidden="true"` to avoid screen reader confusion
- Disabled states properly communicated to assistive technology via `isDisabled`

## Related Components

<RelatedComponents component="pagination" />
