components / pagination

Pagination

Windowed page navigation with current-state emphasis, ellipsis logic, and 44px targets.

Overview

What it is

This section explains the intent of the component before the implementation details.

  • Pagination helps users move through long result sets or collections one page at a time.
  • The DK contract focuses on readable current-state emphasis and dependable windowing rather than link-builder abstractions.

Aliases

pager

Decision guide

How to choose it

Use these notes to decide quickly whether this is the right DK component for the job.

Decision guide

  • Choose Pagination when the interaction should feel deliberate, documented, and reusable across product surfaces.
  • If the scenario is more specialized than the current Pagination contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

  • Keep the Pagination label, value, or status language direct enough to scan quickly.
  • Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

  • Do not hide the main purpose of Pagination behind decorative copy or overloaded surface treatments.
  • Do not stretch Pagination into a workflow it was not designed to handle just because the visuals are close.

Usage

When to use

Prefer these situations when choosing this component.

  • Use Pagination when a list or table spans multiple discrete pages.
  • Expose it near the content it controls so page changes stay contextual.

Usage

When not to use

These patterns are better served by a different component or a simpler surface.

  • Do not use Pagination when infinite scroll or direct filtering would be more useful.
  • Do not overload the control with unrelated sort or density settings.

Anti-patterns

  • Using Pagination as a generic layout container instead of a purpose-built interaction or content surface.
  • Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

  • Migrate legacy pagination usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
  • Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

Anatomy

Structural parts

The anatomy explains which pieces matter to the recipe and accessibility model.

pagination container

root

Wraps the page buttons and ellipsis markers.

page button

page

Navigates to a specific page.

current page marker

current

Shows the currently active page with stronger emphasis.

API

Public interface

The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.

Props

NameTypeDefaultDescription
pagenumber—Current active page.
pageCountnumber—Total number of pages.
siblingCountnumber1Number of sibling pages shown around the current page.
size'sm' | 'md''md'Chooses the pagination size recipe.
onChange(detail: { value: string | undefined }) => void—Callback fired when the current page changes.
themeThemeContract—Overrides the compiled DK theme used to resolve tokens and recipes for this component.

Events

NamePayloadDescription
change{ value: string | undefined }Fires when the component commits a new value.

Slots

NameDescription
defaultPagination is prop-driven in v1 and does not expose custom slots.

Recipes

Variants, sizes, and states

These notes summarize the intended recipe surface rather than exposing raw implementation detail first.

Variants

  • default: Pagination uses one structural recipe and varies mainly by size.

Sizes

  • sm: Compact pagination
  • md: Default pagination

States

  • rest: Inactive page button
  • current: Active page
  • disabled: Unavailable boundary action

Accessibility

Accessibility contract

This is the behavior the component promises to assistive tech and keyboard users today.

Semantics

  • Uses button-like pagination controls with a clear current page state.

Keyboard

  • All pagination actions are reachable in normal tab order.

Screen readers

  • Current page state should be understandable without relying on color alone.

Checklist

  • Verify the visible label or title still produces a clear accessible name.
  • Verify focus remains obvious in every supported state and size.
  • Verify disabled, selected, and error states do not rely on color alone.

Implementation

Tokens and slot vars

This section shows the representative compiled slot variables that the runtime consumes for the selected design system.

root

--dk-pagination-gap
0.375rem

nav

--dk-pagination-nav-fg
#16181c

item

--dk-pagination-item-bg
#f2f5fb
--dk-pagination-item-fg
#16181c
--dk-pagination-item-border
#95989d
--dk-pagination-item-border-width
1px
--dk-pagination-item-radius
999px
--dk-pagination-item-size
0.875rem
--dk-pagination-item-block-size
44px
--dk-pagination-item-inline-size
44px

current

--dk-pagination-current-bg
#d7e9ff
--dk-pagination-current-fg
#000f4d
--dk-pagination-current-border
#2072e4
--dk-pagination-current-size
0.875rem

ellipsis

--dk-pagination-ellipsis-fg
#95989d
--dk-pagination-ellipsis-size
0.875rem

Implementation notes

  • Pagination is button-driven in v1. URL-building or link-first pagination can be composed around it later if needed.

Implementation checklist

  • Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
  • Keep theme overrides token-driven so proofs and recipes stay meaningful.
  • Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.

Examples

Copy-paste examples

Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.

Examples
3
Depth
baseline

Starter

1 example

starter

Starter: short result set

A standard paged result control.

Copy snippet

<Pagination page={4} pageCount={12} />

Common patterns

1 example

common

Common: dense list pager

Smaller pagination works well near tables and dense lists.

Copy snippet

<Pagination size="sm" page={2} pageCount={8} />

Edge cases

1 example

edge

Edge: long page range

Windowing and ellipsis keep very long ranges readable.

Copy snippet

<Pagination page={42} pageCount={180} siblingCount={2} />

Verification

Curated proof fixtures

Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.

pagination-md

pass

size=md

  • Contrast: 89.9 Lc
  • Target: 44px
  • Layout: 71 / 280, 420