Pagination

A navigation component for traversing paged content. Built on Radix UI Slot with CVA variants, accessible ARIA semantics, and full asChild polymorphic composition.

Prefer AI-assisted development?

This documentation is available via the Catalyst MCP Server. Learn how to connect →

Catalyst Pagination wraps Radix UI Slot with built-in design tokens, CVA variants, and WCAG 2.2 AA accessibility defaults — giving you first/previous/next/last controls, numbered page links, and ellipsis support with zero configuration.

Preview

Installation

npm install @pmi/catalyst-pagination

import {
  PaginationRoot,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationPrevious,
  PaginationNext,
  PaginationEllipsis,
} from '@pmi/catalyst-pagination';

Common Patterns

With Ellipsis

Use PaginationEllipsis to collapse large page sets. Clicking the ellipsis jumps to the nearest hidden page.

Preview

API Reference

Pagination is a compound component. The sections below summarize the shared API surface for each part.

PaginationRoot

The wrapping <nav> element. Sets role="navigation" and a default aria-label="pagination".

PaginationContent

The <ul> list that arranges items in a flex row. Accepts all standard ul props and forwards ref.

PaginationItem

A plain <li> wrapper. Accepts all standard li props and forwards ref.

PaginationLink

The core interactive element — renders as <a> by default or any element via asChild (powered by Radix UI Slot).

PaginationPrevious

Wraps PaginationLink for backward navigation. Accepts the same props as PaginationLink. Always provide an aria-label.

PaginationNext

Wraps PaginationLink for forward navigation. Accepts the same props as PaginationLink. Always provide an aria-label.

PaginationEllipsis

Wraps PaginationLink for skipped page indicators. Accepts the same props as PaginationLink. Always provide an aria-label describing the hidden pages.

Accessibility

Pagination is designed to meet WCAG 2.2 AA standards.

Keyboard Interactions

Key	Action
`Tab`	Moves focus to the next pagination control
`Shift + Tab`	Moves focus to the previous pagination control
`Enter`	Activates the focused link or button
`Space`	Activates the focused control when rendered as `asChild` button

ARIA

PaginationRoot renders <nav role="navigation" aria-label="pagination"> — override aria-label when multiple pagination instances exist on the same page.
PaginationLink sets aria-current="page" on the active page and aria-disabled on disabled controls.
Disabled items receive tabIndex={-1} so they are skipped by keyboard navigation.
Always provide a descriptive aria-label on PaginationPrevious, PaginationNext, and PaginationEllipsis — icon-only controls have no visible text.
When using custom CVA styles, verify color contrast meets WCAG 2.2 AA (4.5:1) in both light and dark modes.

Choosing the Right Component

Use Pagination when users need to navigate between discrete pages of content. Reach for a different primitive when:

If you need…	Use instead
Inline page navigation within a data table	Data Table (built-in pagination)
Tab-based section switching on one page	Tabs
A horizontal list of navigation links	Navigation Menu

Pagination
v0.3.2
Documentation Under Review