Pagination

Playground

Installation

pnpm add @tessinaui/ui

Usage

import { Pagination } from "@tessinaui/ui";

<Pagination count={10} defaultPage={1} />

Controlled, when the page lives in your own state:

<Pagination count={10} page={page} onChange={setPage} />

From a record count instead of a page count:

<Pagination totalItems={128} pageSize={20} />

With jumps straight to the ends:

<Pagination count={50} defaultPage={25} showFirstButton showLastButton />

As real links, for crawlable pagination:

<Pagination count={10} getHref={(page) => `/results?page=${page}`} />

When to use it

Reach for Pagination when the reader needs to know where they are in a finite set, jump to a specific point, or link to one — search results, a data table, an archive.

Reach for something else when they are browsing rather than navigating. Image grids, activity feeds and mobile timelines almost universally use infinite scroll or a "Load more" button instead; of the media-grid and feed products sampled for this component, not one paginated. A "Load more" button is a Button, not a degenerate pager.

Examples

Default

A numbered row with chevron nav buttons and ellipsis truncation.

Responsive

The default layout="auto" shows the number row from sm up and a compact counter below it. Narrow the preview to see the swap.

The reason is arithmetic: below md every item is floored to a 44px touch target, so nine of them plus gaps need about 430px — more than a phone has. Shrinking the items would break the touch target, so the count drops instead. The swap is CSS-only, so it survives server rendering without a hydration mismatch.

Simple

layout="simple" is the counter at every width — the most common shape in the wild, and the one most mobile apps use. getStatusLabel reformats it.

Variants

Three active-page styles — default, primary, and outline.

Sizes

Five size tokens from xs to xl.

Rounded

Six radii. Every painted corner derives proportionally, none included.

Nav styles

Navigation buttons as chevron icon, text label, or none. The labels are overridable for wording and for translation.

First and last

showFirstButton and showLastButton add double-chevron jumps outside Previous and Next.

Truncation

siblingCount widens the window around the current page; boundaryCount pins pages at each end. A marker is never used to hide a single page — that page is printed instead. These use layout="numbers", so they stay on one line on a phone by taking the compact density.

Controlled

Drive the active page from external state via page and onChange.

Total items

Give totalItems and pageSize instead of count and the page count is derived, partial last page included.

Range label

PaginationRange renders "1–20 of 128 items". It is a separate export because the three products that show it put it in three different places.

Page size

PaginationPageSizeSelect composes the house Select. Changing the size keeps the first record you were looking at on screen rather than resetting to page 1.

Jump to page

PaginationJump commits on Enter or blur — never per keystroke, which would fetch page 1 on the way to typing "12".

Toolbar

The three-zone table footer: range, pager, page size, all agreeing through one PaginationRoot.

Links

getHref turns items into real anchors, so pages are crawlable and openable in a new tab. Previous and Next carry rel="prev" / rel="next". Use renderLink to route them through next/link.

Loading

loading marks an in-flight page change — the pager goes busy but every control stays focusable. PaginationSkeleton is the different case: there is nothing to page through yet.

On a colour plate

tone="on-color" (or an enclosing coloured Surface, which supplies it) draws the pager in the plate's own ink. On a plate you paint yourself, also publish its ink with surfaceInkClasses — the pager's text, its current-page chip and its focus ring's gap all read the plate from there, and fall back to the page without it.

RTL

dir="rtl" flips the chevrons and mirrors the control order, so the largest jump stays outermost in the reading direction.

API Reference

Pagination

PaginationRoot

Optional state owner. Wrap parts in it only when more than one has to agree.

PaginationRange

PaginationPageSizeSelect

PaginationJump

PaginationSkeleton

Layouts

numbers is the one layout that gives up the 44px touch target. Nine 44px cells plus gaps need about 430px, so the row cannot both keep that target and stay on one line on a phone. auto and simple resolve it by showing fewer cells and keep the 44px; numbers keeps every cell and drops to the compact density instead — still above the WCAG 2.5.8 (AA) 24px minimum, but below 2.5.5 (AAA). That is the whole reason auto is the default.

Nav styles

Variants

Accessibility

• Renders as <nav aria-label="Pagination">. There is no redundant role="navigation" — <nav> already carries it, and the old "pagination navigation" label made screen readers say "navigation" twice. Give each pager its own aria-label when a page has more than one.
• The active page carries aria-current="page". Every control has a descriptive name, overridable through getPageAriaLabel.
• A page change is announced. A polite live region speaks "Page 4 of 12" and clears after two seconds. Without it, activating a page number moves focus nowhere and silently replaces content the screen-reader cursor is not on — the change is invisible to assistive technology.
• Boundary controls are aria-disabled, never natively disabled. Previous on page 1 stays focusable and dimmed in place. A natively disabled button that switches off while focused drops focus to <body>, which is what the old implementation did on every trip back to page 1. Link mode forces the same answer independently: an <a> has no native disabled state.
• Truncation markers are not silent. Each carries sr-only text naming what it hides — "Pages 2 through 8 not shown" — so the jump from 1 to 9 is explained rather than mysterious.
• Touch targets are floored at 44×44 below md (WCAG 2.5.5) in auto and simple. This is why auto swaps to the counter on phones rather than shrinking items. layout="numbers" is the documented exception: it keeps every cell on one line at the compact density, so its targets meet the WCAG 2.5.8 (AA) 24px minimum but not the 44px enhanced target. Prefer auto unless you specifically need every page number visible on a phone.
• PaginationSkeleton is a role="status" region with real text, so it announces on insertion instead of being an empty application status.

Keyboard

There is no roving tabindex and no arrow-key model. APG has no pagination pattern, and every control here is independently meaningful — often a link. Roving would hide all but one of them from keyboard users and fight the screen-reader virtual cursor. Every surveyed implementation tabs through.

Assistive technology

The announcement is doubled under next dev because React Strict Mode double-invokes effects; a production build announces once.

Migrating

1. Boundary Previous/Next are no longer natively disabled. Selectors or tests matching :disabled / [disabled] on them must target [aria-disabled="true"]. Whole-component disabled is unchanged.
2. The landmark's default name is now "Pagination", not "pagination navigation". Pass aria-label to pin your own.
3. Disabled opacity moved from 40% to 50%, matching the rest of the library. Boundary dimming stays at 40%.
4. PaginationSkeleton.showNav is gone — use navStyle="none".
5. The default layout is now responsive. If you depend on the number row at every width, set layout="numbers" explicitly — and note that it trades the 44px touch target for the compact density on phones in order to stay on one line.

Notes

• Truncation uses the MUI usePagination algebra: boundaryCount pages pinned at each end, siblingCount around the current page, the rest collapsed. When a marker would stand for exactly one page, that page is printed instead.
• Controlled vs uncontrolled is decided once, at mount. Switching between them mid-life warns in development rather than silently mirroring state.
• No headless dependency. Base UI has no pagination primitive; this is plain React state over the house Button/Select tokens.