Pagination

Import

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

Usage

<ComponentPreview name="pagination-basic" />

Anatomy

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

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

<ComponentPreview name="pagination-sizes" />

With Ellipsis

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

Simple (Previous / Next)

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

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" />

Controlled

<ComponentPreview name="pagination-controlled" />

Disabled

<ComponentPreview name="pagination-disabled" />

Styling

Passing Tailwind CSS classes

You can customize individual Pagination parts:

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.

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

  .pagination__link {
    @apply rounded-md;
  }

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

HeroUI follows the BEM 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):

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

Pagination.Summary Props

Pagination.Content Props

Pagination.Item Props

Pagination.Link Props

Pagination.Previous / Pagination.Next Props

Pagination.PreviousIcon / Pagination.NextIcon Props

Pagination.Ellipsis Props

Accessibility

The Pagination component is built on React Aria's Button 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.