Skip to content

Design system

Documentation

DesignComponents / Pagination

Components / Pagination

Beta

Pagination

Navigate through a feature-owned result set without taking ownership of its data.

On this page

Examples

Controlled page

The feature owns the current page and can use it to derive the visible slice of rows.

Controlled pagination for 42 items

Uncontrolled page

Use defaultPage when the pagination does not need to be mirrored into feature state.

Uncontrolled pagination with page two selected

Try the props

Change the total count and disabled state while the control owns its initial page.

Pagination property playground

When to use

Use Pagination when the person needs to move through a known result set. It only reports the requested page; the feature decides which records to render or fetch. Keep filters staged when the screen has an Apply action.

Usage

import { Pagination } from "@phuctech/ui/components/pagination";

<Pagination count={42} pageSize={10} page={page} onPageChange={setPage} />

API

Component API
PropTypeDefaultDescriptionConstraints
countnumberrequiredTotal result count used to calculate the page range.Finite values are floored at zero.
pageSizenumber10Number of records per page.Must be a finite positive number; invalid values use 10.
page / defaultPagenumber1Controlled page or initial uncontrolled page.Use one model; displayed values are clamped to the current page count.
onPageChange(page: number) => void—Called when a valid page is requested.It does not fetch data or change a controlled page itself.
siblingCountnumber1Visible page numbers around the current page.Finite values are clamped to 0–2.
disabled / loadingbooleanfalseDisables page controls; loading also sets aria-busy.Keep the result range available while controls are unavailable.
aria-label / nav propsstring / HTMLNavElement props"Pagination"Names the navigation landmark and preserves native nav attributes.Use a more specific name if a page has multiple pagers.

Tokens

Component tokens
TokenRoleEffective valueUsage
control size sm / focus-ringPage controlsShared control scaleMatches Button and keeps keyboard focus visible.
muted-foregroundResult range and ellipsesSecondary textKeeps range context visible without competing with the current page.

Accessibility

Pagination is a named navigation landmark. Every page button has an action-oriented accessible name; the current page uses aria-current="page", and range changes are announced politely. Buttons work with Tab, Enter, and Space.

Do and don’t

Do

Reset the page in feature state when filters change the result set.

Don’t

Put data loading or per-row requests inside Pagination.

  • Table presents structured rows.
  • Data Table composes staged filters, selection, and pagination.