Skip to main content

Overview

Pagination renders page number buttons, previous/next arrows, and an ellipsis for large page counts. It can be controlled or uncontrolled and pairs naturally with the Table component.

Installation


Usage


Variants

Basic

With Ellipsis (Many Pages)

Usage with Data Table


API Reference

number
Controlled current page (1-indexed).
(page: number) => void
Callback fired when the user navigates to a different page.
number
default:"1"
Uncontrolled default page.
number
Total number of pages (required).
number
default:"1"
Number of page buttons shown on each side of the current page.
boolean
default:"true"
Shows first («) and last (») page jump buttons.
string
default:"md"
Button size. Values: sm · md · lg
string
Additional Tailwind classes for custom overrides.

Accessibility

  • Pagination uses a <nav> element with aria-label="Pagination"
  • Active page button has aria-current="page"
  • Disabled previous/next buttons have aria-disabled="true"
  • Ellipsis elements use aria-hidden="true" as they are decorative
  • Previous/Next buttons have descriptive aria-label attributes

Do’s & Don’ts

Do

  • Always pair Pagination with a data table or list
  • Show the total count of items alongside the pagination control
  • Use siblingCount={2} for very large datasets (100+ pages)
  • Keep the Pagination at the bottom of the data, aligned to the right

Don't

  • Don’t use Pagination for fewer than 2 pages — hide it entirely
  • Don’t change totalPages during interaction unless data has changed
  • Don’t place Pagination above the data — users expect it at the bottom
  • Don’t use Pagination when infinite scroll is more appropriate for the UX