role navigation

Pagination draft v0.1.0

Lets people move between the pages of a long list, with the current page marked.

A pagination splits a long list of results into pages and lets people go to a page by its number, or to the previous and next ones. It shows which page is current. The pages are links: each one has a destination, so the browser handles history and focus. Which page numbers to show (all, a window around the current one) is the application's choice: the component renders the list it is given.

Decisions

From decisions in packages/components/specs/components/pagination.spec.json, newest first. Every active decision is implemented by the spec, the tokens, the web implementation and the guidelines.

Behaviour

Pages are links with destinations, in a navigation landmark named Pagination; the current page is not a link and is exposed as current; previous and next are links with a visible word, disabled without destination. The component renders the pages it is given and decides nothing about which numbers to show.

Links give history, focus and announcements for free; a pagination made of buttons needs script.

links-not-buttons · 2026-10-03 · v0.1.0

WAI-ARIA 1.2: navigation role WAI-ARIA 1.2: aria-current (page)

Color

Links are primary text on a transparent background, tinted with the subtle neutral fill on hover and its hover step on press (the Button's ghost tints); the current page is the accent neutral fill with its on-accent text; disabled links take the disabled text color.

link-colors · 2026-10-03 · v0.1.0

pagination.link.background.*pagination.link.color.*

Size

Two sizes from the space scale: small (32 px links, 14 px text, 20 px chevrons) and medium (40 px, 16 px, 24 px, the default), with 4 px corners and 4 px between links.

sizes · 2026-10-03 · v0.1.0

pagination.link.size.*pagination.link.typography.*pagination.icon.size.*pagination.link.border-radiuspagination.container.gap