# Pagination · HeroUI

> Page navigation with composable page links, previous/next buttons, and ellipsis indicators

- Page: https://jiguang132.com/systems/heroui/docs/components/pagination
- Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## Import

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

### Usage


> Example `pagination-basic`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/pagination


### Anatomy

Import the Pagination component and access all parts using dot notation.

```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>
);
```

### Sizes


> Example `pagination-sizes`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/pagination


### With Ellipsis


> Example `pagination-with-ellipsis`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/pagination


### Simple (Previous / Next)


> Example `pagination-simple-prev-next`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/pagination


### With Summary


> Example `pagination-with-summary`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/pagination


### Custom Icons

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


> Example `pagination-custom-icons`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/pagination


### Controlled


> Example `pagination-controlled`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/pagination


### Disabled


> Example `pagination-disabled`: interactive preview on https://jiguang132.com/systems/heroui/docs/components/pagination


## Styling

### Passing Tailwind CSS classes

You can customize individual Pagination parts:

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

function CustomPagination() {
  return (
    <Pagination className="gap-8">
      <Pagination.Content className="gap-2">
        <Pagination.Item>
          <Pagination.Link className="rounded-md" isActive>1</Pagination.Link>
        </Pagination.Item>
      </Pagination.Content>
    </Pagination>
  );
}
```

### Customizing the component classes

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;
  }
}
```

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
- `.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
- `.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 Props

| 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 Props

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

### Pagination.Content Props

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

### Pagination.Item Props

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

### Pagination.Link Props

| 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 Props

| 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 Props

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

### Pagination.Ellipsis Props

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

## 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`

> **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.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt