Pagination

Page navigation with a windowed range and current-page marker.

Overview

  • Use pagination for result sets that users navigate one page at a time.

Aliases

pager

When to use

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

When not to use

  • 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.

Structural parts

pagination container

root

Wraps the page buttons and ellipsis markers.

page button

page

Navigates to a specific page.

current page marker

current

Identifies the active page.

Public interface

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: { page: number }) => void—Receives the new page number.
themeThemeContract—Sets the theme used to resolve component styles.
Events
NamePayloadDescription
change{ page: number }Fires with the new page number.
Slots
NameDescription
defaultPagination is prop-driven and does not expose custom slots.

Variants, sizes, and states

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

Semantics

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

Keyboard

  • All pagination actions are reachable in normal tab order.

Screen readers

  • Identify the active page with text or state attributes as well as color.

Checklist

  • Verify that the control has an accessible name.
  • Verify that keyboard focus is visible in every state and size.
  • Identify disabled, selected, and error states with text or symbols as well as color.

Tokens and CSS variables

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 renders buttons. Handle page changes to update the URL.

Examples

Starter

Short result set

A standard paged result control.

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

Common patterns

Dense list pager

Smaller pagination works well near tables and dense lists.

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

Edge cases

Long page range

Windowing and ellipsis keep very long ranges readable.

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

Mathematical fixtures

Calculated fixtures; browser evidence is not collected. Layout estimates use declared text behavior and maximum token values.

pagination-md

pass

size=md

  • Evidence: mathematical
  • Coverage: complete (3 / 3 declared kinds evaluated)
  • Declared: contrast, target, layout
  • Evaluated: contrast, target, layout
  • Contrast: 89.9 Lc
  • Target: 44 px
  • Layout: root · single-line 71 px single-line estimate; 71 px minimum width
    280 px: pass 420 px: pass