DocsPlatform

Pagination

One page binding, and the machine does the rest: page count, clamping at both ends, moving between pages, and the range maths that decides where the gaps go. That range calculation comes from the frozen oracle, so it matches the legacy output exactly. All four layers share the one behaviour contract.

Live machine

The shipped paginationMachine, running here through createService with 300 rows at 25 per page. The cells, the state strip, and the transition list are all derived from the machine object — interact with either side and watch the same snapshot change.

pagination · live via createService

States · walked from the machine

ready

Transitions from here · click to send

Context

{
  "mode": "uncontrolled",
  "page": 3,
  "total": 300,
  "pageSize": 25,
  "siblingCount": 1,
  "pageCount": 12,
  "range": [
    1,
    2,
    3,
    4,
    "…",
    12
  ]
}

Log · newest first

No events yet — use the component above or send a transition.

The layers

Machine is pure state with no DOM. Headless maps that state to framework-native anatomy and ARIA. Styled keeps the existing Grassroot visual recipe while delegating behaviour. Vanilla mounts the same headless contract without a framework.

Behaviour contract

The machine owns page clamping, boundary navigation, sibling ranges, ellipses, and controlled page requests. Adapters translate DOM events and render machine snapshots. Not one of them keeps a second reducer or re-filters the collection behind your back.

Controlled bindings emit serialisable change requests, and only adopt the parent's state once it comes back in through input.
Uncontrolled bindings commit straight to machine state, and still emit the same request object, so a consumer can watch either way.
Keyboard, pointer, focus, dismissal, and accessibility behaviour are shared across vanilla, React, Vue, Solid, Svelte, and Angular.

Evidence

The authoritative source files are:

packages/ui-machines/src/pagination/index.ts
packages/ui-headless/core/src/pagination/pagination.spec.md
packages/ui-headless/core/src/pagination/vanilla.ts
packages/ui-headless/browser-contract/pagination.contract.ts, the shared browser assertions.
Each framework package has a matching browser/pagination.spec.ts contract entry.