Pagination

A headless, accessible pagination primitive with Previous, Next, page links, and ellipsis.

Features

Semantic navigation
Composable parts
Controlled or uncontrolled page state
Configurable visible page window
Current page state
Previous and next controls
Router agnostic

Installation

npm install @ariaui/pagination

Examples

Previous and next controls, numbered page links, and ellipsis gaps. The live snippet keeps page state on Root and renders the visible page window through Pages. Style links with className; set aria-label on the root nav when you wire real routes.

Uncontrolled

Preview

No preview output yet.

live.tsxReady

Controlled

Preview

No preview output yet.

live.tsxReady

Anatomy

tsx

import Pagination from "@ariaui/pagination";

export default function Example() {
  return (
    <Pagination.Root>
      <Pagination.Content>
        <Pagination.Item>
          <Pagination.Previous />
        </Pagination.Item>
        <Pagination.Pages>
          <Pagination.Item>
            <Pagination.Link />
            <Pagination.Ellipsis />
          </Pagination.Item>
        </Pagination.Pages>
        <Pagination.Item>
          <Pagination.Next />
        </Pagination.Item>
      </Pagination.Content>
    </Pagination.Root>
  );
}

API Reference

Root

Navigation landmark wrapping the pagination controls. Owns page state and renders as a semantic <nav> with an accessible label.

Prop	Type	Default
totalPages	number	1
maxVisiblePages	number	5
page	number	—
defaultPage	number	1
onPageChange	(page: number) => void	—

Attribute	Values
aria-label	'pagination'

Content

Unordered list that contains the pagination Items.

Item

List item wrapper for a Link, Previous, Next, or Ellipsis.

Link

Anchor representing a page. Pass `page` when composing links manually; inside Pages it reads the generated page item from context.

Prop	Type	Default
page	number	—
isActive	boolean	false
activeClassName	string	—

Attribute	Values
aria-current	"page" when current

Pages

Repeats its children for each generated page-window item from Root state.

Pre-configured Link pointing to the previous page.

Attribute	Values
aria-label	'Go to previous page'

Pre-configured Link pointing to the next page.

Attribute	Values
aria-label	'Go to next page'

Ellipsis

Decorative placeholder for skipped page numbers. Inside Pages it renders only for generated gap items.

Prop	Type	Default
label	React.ReactNode	—

Attribute	Values
aria-hidden	true

Accessibility

Pagination follows standard navigation patterns:

Root renders as a semantic <nav> with aria-label="pagination" — discoverable as a landmark by assistive tech.
Content is an unordered list of Items, each containing a single interactive Link, Previous, Next, or Ellipsis.
Link with isActive sets aria-current="page" so screen readers announce the current page.
Link renders only for numbered items when composed inside Pages without an explicit page, and inherits the current-page behavior from Root state.
Previous and Next have aria-label="Go to previous page" and "Go to next page" by default so their icon-only variants stay understandable.
Ellipsis renders only for gap items when composed inside Pages, is marked aria-hidden, and carries no interactive role; pair generated ellipses with label when needed.
Focus management uses native anchor semantics — Tab / Shift+Tab to move between controls, Enter to activate.