Pagination

Previous, the pages, Next — the library’s own buttons in a row, space/4 apart: ghost for every page, secondary (outlined) for the current one, an ellipsis before the last page.

Beta · Navigation and overlay · packages/css/src/components/pagination.css · React on Base UI: @pepperui/pagination

.pui-pagination — the library’s buttons at space/4: ghost pages, the current one secondary (aria-current="page"), __ellipsis.

Pagination — every size and every stateOpen in the workshop

Sizes across, states down.

What it is for

• Size medium / small (Button’s)
• Previous and Next are exposed Buttons (ghost, a chevron leading / trailing); Page 1–5 exposed — the current page is the secondary one, swap it on the instance; Has page 4 / 5 (three by default), Has ellipsis, Has last page
• One outlined page, never two; a disabled Previous stays visible
• Right-aligned in a Data table’s footer beside the range text; alone under a list

Use when a table or a list is longer than one page and the person needs to know where they are.

Do not use when the list can load more on scroll (a ‘Load more’ Button); fewer than two pages (nothing); stepping through a flow (Stepper).

Relates to Data table, Table, Button, Button - secondary, Button - ghost, Icon button.

Anti-patterns numbered pills instead of buttons · a Previous that vanishes when disabled · a page-size Select without the range text · more than seven page buttons.

Keywords: pagination, pager, pages, previous next, page numbers

Figma — page Pagination: Pagination (2 variants)

shadcn: pagination

The markup — copy this

The class, the parts, and nothing that is not in the package. The same block opens pagination.css.

<nav class="pui-pagination" aria-label="Pages">
  <a class="pui-button pui-button--ghost" href="…"><span class="pui-icon pui-button__icon">…chevron-left…</span>Previous</a>
  <a class="pui-button pui-button--ghost" href="…">1</a>
  <a class="pui-button pui-button--secondary" aria-current="page" href="…">2</a> …
  <span class="pui-pagination__ellipsis" aria-hidden="true">…</span>
  <a class="pui-button pui-button--ghost" href="…">Next<span class="pui-icon pui-button__icon">…chevron-right…</span></a></nav>

The modifiers

	What it is	Note
Size	on the buttons (pui-button--small for the small pager)	—

Rule — one outlined page, never two; a disabled Previous stays visible.

Accessibility — measured, not assumed

Every number here is measured on the rendered component: contrast (npm run contrast:render), the focus ring (npm run focus) and the keyboard (npm run keyboard). The floors are principle 12’s.

Contrast

ink on ground	reads	floor	the matrix calls it
#0b0202 on #ffffff	20.51	4.5	text.default on surface.page (promised)	ok

1 distinct pair(s) rendered, 0 that axe calls a violation.

The focus ring

12 of 12 focus stop(s) in this block meet WCAG 2.4.13 on screen — the same crop screenshotted focused and unfocused, and the difference measured.

Keyboard

Nothing in this component claims an ARIA role with a keyboard contract; its controls are ordinary ones and the browser already gives them their keys.

Tab order across the whole library is document order over 344 stops, and Shift+Tab is its exact reverse — no keyboard trap anywhere (WCAG 2.1.2).