Skip to main content

Pagination

Page navigation for multi-page content. Provides page number links, previous/next controls, and first/last controls so users can step through long lists or search results. Reach for pagination whenever content is split into numbered pages.

Usage​

When to use

  • Long lists of results split across multiple pages
  • Archives, search results, or content listings with a known total
  • Any time the user benefits from jumping directly to a specific page

When not to use

  • Infinite feeds where content loads as the user scrolls
  • Short lists that fit on a single page
  • Navigating between unrelated pages - use navbar instead

Do

  • Show the current page clearly with aria-current="page"
  • Include previous/next controls for sequential traversal
  • Collapse long ranges with an ellipsis

Don't

  • Hide the current page number from the visible control
  • Use link text like "click here" for previous/next - use "Previous" and "Next" with aria-label

API​

Props​

PropTypeDefaultDescription
itemsobject-Pagination entries grouped by role: first, previous, pages (keyed by page number), next, and last. Each boundary item has {text?, url} and pages is a map of page number to {url}.
currentnumber-The active page number. Must match a key in items.pages.
total_pagesnumber-Total number of pages. Used to derive disabled state on boundary controls.
use_ellipsisboolean-When true, inserts ellipsis markers between the page window and the first and last page.
labelstring-aria-label for the nav landmark.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.roundedShape-Rounded corners.
.squareShape-Sharp corners.
.pillShape-Fully rounded ends.

Examples​

Default​

Basic pagination with page numbers and previous/next controls.

With first and last​

Pagination with first and last controls in addition to previous/next.

Long range with ellipsis​

Pagination collapsing a long range with an ellipsis indicator.

Disabled​

Pagination on the first or last page with disabled previous/next controls.

Sizes​

The three size values, which scale the font size and control padding together.

Shapes​

The three shape values, which set the corner geometry of each control.

Accessibility​

  • WCAG 2.2 AA
  • Wrapped in <nav> labeled as pagination
  • Active page identified to assistive technology
  • Disabled controls identified to assistive technology
  • Previous/next controls have accessible names
  • navbar - general-purpose link navigation
  • toc - in-page navigation