Pagination

Import

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

Usage

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

With Ellipsis

Simple (Previous / Next)

With Summary

Custom Icons

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

Controlled

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.