J3W1 / DESIGN SYSTEM

Pagination

Page links for a long result set; the current page takes the selection fill and aria-current, and the compact form reads "3 of 12" between previous and next.

stable · LIGHT DOM · 1.1.0

Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.

Standalone example ↗Copy file manifest Canonical JSON Vue gallery ↗Prepare an agent kit →

Live variants

default

Example destination: pg 2

Example destination: pg 1

Example destination: pg 3

Example destination: pg 4

Example destination: pg 12

<j3w1-pagination id="example-pagination-default"><nav class="pagination" aria-label="Pagination">
  <ul class="pagination-list">
    <li class="pagination-item"><a class="pagination-link pagination-edge pagination-prev" href="#example-pagination-default-pg-2" aria-label="Previous page, 2"><span class="pagination-glyph" aria-hidden="true">‹</span> Prev</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#example-pagination-default-pg-1" aria-label="Page 1" data-page="1">1</a></li>
    <li class="pagination-item"><a class="pagination-link" href="#example-pagination-default-pg-2" aria-label="Page 2" data-page="2">2</a></li>
    <li class="pagination-item"><a class="pagination-link pagination-current" href="#example-pagination-default-pg-3" aria-label="Page 3" aria-current="page" data-page="3">3</a></li>
    <li class="pagination-item"><a class="pagination-link pagination-link-demo-target" href="#example-pagination-default-pg-4" aria-label="Page 4" data-page="4">4</a></li>
    <li class="pagination-item"><span class="pagination-gap" aria-hidden="true">…</span></li>
    <li class="pagination-item"><a class="pagination-link" href="#example-pagination-default-pg-12" aria-label="Page 12" data-page="12">12</a></li>
    <li class="pagination-item"><a class="pagination-link pagination-edge pagination-next" href="#example-pagination-default-pg-4" aria-label="Next page, 4">Next <span class="pagination-glyph" aria-hidden="true">›</span></a></li>
  </ul>
</nav><p id="example-pagination-default-pg-2" tabindex="-1" class="j3w1-example-target">Example destination: pg 2</p><p id="example-pagination-default-pg-1" tabindex="-1" class="j3w1-example-target">Example destination: pg 1</p><p id="example-pagination-default-pg-3" tabindex="-1" class="j3w1-example-target">Example destination: pg 3</p><p id="example-pagination-default-pg-4" tabindex="-1" class="j3w1-example-target">Example destination: pg 4</p><p id="example-pagination-default-pg-12" tabindex="-1" class="j3w1-example-target">Example destination: pg 12</p></j3w1-pagination>

compact

Example destination: pg 2

Example destination: pg 4

<j3w1-pagination id="example-pagination-compact"><nav class="pagination pagination-compact" aria-label="Pagination">
  <ul class="pagination-list">
    <li class="pagination-item"><a class="pagination-link pagination-edge pagination-prev pagination-link-demo-target" href="#example-pagination-compact-pg-2" aria-label="Previous page, 2"><span class="pagination-glyph" aria-hidden="true">‹</span> Prev</a></li>
    <li class="pagination-item"><span class="pagination-status" aria-current="page"><span class="pagination-status-current">3</span> of 12</span></li>
    <li class="pagination-item"><a class="pagination-link pagination-edge pagination-next" href="#example-pagination-compact-pg-4" aria-label="Next page, 4">Next <span class="pagination-glyph" aria-hidden="true">›</span></a></li>
  </ul>
</nav><p id="example-pagination-compact-pg-2" tabindex="-1" class="j3w1-example-target">Example destination: pg 2</p><p id="example-pagination-compact-pg-4" tabindex="-1" class="j3w1-example-target">Example destination: pg 4</p></j3w1-pagination>

Install and register

Use the exact version. If npm publication is pending, install the release tarball from the installation guide.

npm install --save-exact @j3w1/ui@1.1.0

import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/pagination.css';
import '@j3w1/ui/register/pagination';

Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.

Vue SFC, React, Astro and plain HTML integration →

Copy the complete implementation

npx --package=@j3w1/ui@1.1.0 j3w1-ui copy pagination --out ./vendor/j3w1/pagination

The CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.

Public API

attributes

Name	Type / signature	Meaning
`disabled`	`CustomEvent`	Disable the native controls owned by this instance.
`loading`	`CustomEvent`	Mark the primary control busy and prevent duplicate activation.

properties

Name	Type / signature	Meaning
`disabled`	`boolean`	Delegates disabled state to native children.
`name`	`string`	Native control name; application form keys remain explicit.
`page`	`number`	Current page when using local button-mode pagination.

methods

Name	Type / signature	Meaning
`refresh`	`(): void`	Reconnect behavior after replacing native child structure.
`focus`	`(options?: FocusOptions): void`	Focus the first usable native control.

events

Name	Type / signature	Meaning
`j3w1-page`	`CustomEvent`	Local page choice changed; native href links continue to navigate.

Dependencies and verification

Registered components: none. Style dependencies: none.

Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.

Full implementation manifest, API and token dependency closure

Canonical specification

Purpose

Moves through a result set that is split into pages. Pagination is for sets whose size is known; use a “load more” button or infinite scroll for feeds, and a range field for jumping to an arbitrary offset.

Anatomy

A nav labelled “Pagination” holding a ul: previous, the page links with an aria-hidden … gap where pages are skipped, next. Every page link is a square target in color.text.default with no border; the current page is filled with color.interaction.selection.bg and color.text.on-selection. The compact variant keeps previous and next and replaces the numbers with “3 of 12”, the current number in color.text.bright.

States

State	Visual	Non-colour channel
default	text `color.text.default`; no fill; no border	—
hover	background → `color.interaction.hover.bg`	cursor: pointer
focus-visible	ring 1px dashed `color.interaction.focus.ring` at −2px; on the current page the ring is `color.interaction.focus.ring-container`	the ring
current	fill `color.interaction.selection.bg`; text `color.text.on-selection`; no hover	`aria-current="page"`
disabled	text `color.text.disabled`; no fill; no hover	`aria-disabled="true"`; no `href`; cursor: not-allowed

Pressing a link uses color.interaction.pressed.bg for the duration of the press only.

Keyboard

Plain links in document order: previous, the pages, next. A disabled end has no href, so it is not a tab stop and cannot be activated. The current page remains a link to itself so a keyboard user can reload it.

Accessibility

aria-label="Pagination" on the nav; a second pagination on the same page gets a distinct label. Previous and next carry a visible word, not just a glyph, and aria-label gives the target page number when it is known (“Previous page, 2”). The gap is aria-hidden; the list count tells a screen reader how many links follow. Contrast: link text 8.43:1, current text 12.47:1 on the selection fill, ring-container 7.48:1 on the fill, disabled 3.24:1 (exempt). Targets are at least 24×24 CSS pixels in compact density.

Portability

Links with a background and an outline; nothing else. Hosts that cannot remove href from a disabled link use a disabled button for the ends and record it. The compact variant is plain text and two links and ports anywhere.

Non-examples

Rounded or circular page buttons. A border around every page link. The current page marked by colour or bold alone without aria-current. Previous and next as glyph-only links without a label. A disabled end that still has an href. Pagination that hides the last page number. A row that scrolls horizontally.