Pagination

Usage

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

Anatomy

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

Disabled

Simple (Previous / Next)

Controlled

With Ellipsis

With Summary

Custom Icons

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

Customization

Tailwind CSS

Global CSS

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

Styling Reference

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

Pagination.Summary

Pagination.Content

Pagination.Item

Pagination.Link

Pagination.Previous / Pagination.Next

Pagination.PreviousIcon / Pagination.NextIcon

Pagination.Ellipsis

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