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 · 4.0.0. Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.
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@4.0.0import '@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.
Copy the complete implementation
npx --package=@j3w1/ui@4.0.0 j3w1-ui copy pagination --out ./vendor/j3w1/paginationThe 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
Pagination 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.
Report an issue with this component
Tokens
Focus a role to inspect its values; follow its link for persistent usage and source details.
| Part | Role | Value | Use |
|---|---|---|---|
root.bg | color.surface.defaultapproveduse | #0d0707 | D-041 surface.default: color.primitive.modern.panel. |
link.text | color.text.defaultapproveduse | #e99499 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
link.bg-hover | color.interaction.hover.bgapproveduse | #1c1010 | D-041 interaction.hover.bg: color.primitive.modern.hover. |
link.bg-pressed | color.interaction.pressed.bgobserveduse | #420f0c | Pressed fill. |
link.ring | color.interaction.focus.ringobserveduse | #e53935 | 1px dashed focus ring on controls and rows. |
link.text-disabled | color.text.disabledapproveduse | #a3676b | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
current.bg | color.interaction.selection.bgapproveduse | #531310 | Selected row, tab, workspace; D-027 recessed the fill, leaving the 2px indicator and the check to carry selection. |
current.text | color.text.on-selectionobserveduse | #f4eeee | Text on the selection fill. |
current.ring | color.interaction.focus.ringobserveduse | #e53935 | 1px dashed focus ring on controls and rows. |
gap.text | color.text.mutedapproveduse | #d4868b | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
status.text | color.text.defaultapproveduse | #e99499 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
status.emphasis | color.text.brightapproveduse | #ffa2a7 | D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills. |
State matrix
Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).
| State | Default | Compact |
|---|---|---|
default | ||
hover | ||
focus-visible | ||
current | ||
disabled |
Purpose
Moves through a paged result set of known size. Feeds use a “load more” button or infinite scroll; jumping to an arbitrary offset is a range field.
Anatomy
Parts as listed in the anatomy; page links have no border.
States
| State | Visual | Non-colour channel |
|---|---|---|
| default | color.text.default; no fill, no border | — |
| hover | background → color.interaction.hover.bg | cursor: pointer |
| focus-visible | 1px dashed color.interaction.focus.ring at −2px, including the current page | the ring |
| current | fill color.interaction.selection.bg, text color.text.on-selection; no hover | aria-current="page" |
| disabled | color.text.disabled; no fill, no hover | aria-disabled="true"; no href; cursor: not-allowed |
A link shows color.interaction.pressed.bg only while pressed.
Keyboard
As in the key table. The current page stays a link to itself so a keyboard user can reload it.
Accessibility
A second pagination on the same page gets a distinct label. Previous and next
carry a visible word, not just a glyph; aria-label gives the target page
when known (“Previous page, 2”). The list count tells a screen reader how many
links follow. Text meets 4.5:1 and the ring 3:1; disabled ends are exempt
(house floor 3:1). Targets are at least 24×24 CSS pixels in compact.
Portability
Links with a background and an outline; nothing else. A host that cannot
remove href from a disabled link uses a disabled button for the ends and
records it. The compact variant is plain text and two links.
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.
Glyph-only previous and next. A disabled end with an href. Hiding the last
page number. A horizontally scrolling row.
Contrast report
8 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.
| Pair | State | Kind | Foreground | Background | Ratio | Min | Result |
|---|---|---|---|---|---|---|---|
| pagination default text | default | text | color.text.default #e99499 | color.surface.default #0d0707 | 8.72 | 4.5 | pass |
| pagination hover text | hover | text | color.text.default #e99499 | color.interaction.hover.bg #1c1010 | 8.10 | 4.5 | pass |
| pagination focus-visible text | focus-visible | text | color.text.default #e99499 | color.surface.default #0d0707 | 8.72 | 4.5 | pass |
| pagination focus-visible outline | focus-visible | ui | color.interaction.focus.ring #e53935 | color.surface.default #0d0707 | 4.73 | 3 | pass |
| pagination current text | current | text | color.text.on-selection #f4eeee | color.interaction.selection.bg #531310 | 12.47 | 4.5 | pass |
| ring on the current page when focused | current | ui | color.interaction.focus.ring #e53935 | color.interaction.selection.bg #531310 | 3.38 | 3 | pass |
| disabled previous/next (exempt; house floor 3:1) | disabled | ui | color.text.disabled #a3676b | color.surface.default #0d0707 | 4.48 | 3 | pass |
| gap ellipsis on the panel surface | — | text | color.text.muted #d4868b | color.surface.default #0d0707 | 7.22 | 4.5 | pass |
Keys
| Key | Action |
|---|---|
| Tab / Shift+Tab | Moves through previous, each page link and next in order; a disabled end has no href and is not a stop. |
| Enter | Follows the focused link. |
For agents
Component JSON ·Implementation brief ·Build a task kit ·
Related: table data-table link button
Stress fixtures: FX-320 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-STATE-MATRIX