HyPagination

Usage examples on this page are written for Lit / plain HTML (<hy-pagination>). The same component ships as HyPagination in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A navigation control for paging through a large, segmented data set (table rows, search results, a list). Renders numbered page buttons with ellipsis truncation, prev/next (and optional first/last) arrows, an optional rows-per-page selector, and an optional range label.

Controlled by design. The consumer owns pageIndex / pageSize; the component renders that state, emits a single change event on interaction, and the consumer echoes the new state back (slice locally or refetch). This matches hy-table (stateless/controlled) and is the correct model when paired with a state-owning data engine — there is no internal source of truth to drift.

Accessibility: a <nav> landmark with aria-label; the current page button carries aria-current="page"; arrows are disabled at the bounds.

Responsive. A ResizeObserver measures the control's own width and fits the page window to it (the AG Grid / Ant responsive model): siblingCount shrinks as the container narrows, and when even a zero-sibling window no longer fits, the layout collapses to the compact "Page X of Y" form automatically. siblingCount and compact are therefore an upper bound and a forced floor — the rendered window is never wider than the author asks, and compact (when set) pins the compact layout at every width. Until first measured (SSR, first paint) the author's full window renders.

When to use

• A long set of results people move through and come back to: search results, records, orders.

Do

• Show the total, with show-total, when people need to know how many there are.
• Offer show-page-size when people want to see more at once.

When not to use

• Paging an hy-datagrid: set its paginated, no separate pagination.
• Everything fits on one or two screens: show it all.
• A feed people scroll through casually: load more as they scroll.
• The steps of a process: hy-stepper.
• Switching sections of a page: hy-tab-group, or hy-tab-nav when each section has its own URL.

Accessibility: your part

• After a new page of results loads, move focus to the top of the results or announce the change.

Examples

Basic (controlled)

<hy-pagination total="100" page-index="0" page-size="10"></hy-pagination>

With size selector and range label

<hy-pagination total="248" page-index="2" page-size="20" show-page-size show-total></hy-pagination>

Forced compact (pins "Page X of Y" at every width)

<hy-pagination total="100" page-index="0" page-size="10" compact></hy-pagination>

API

Properties

Property	Attribute	Type	Default	Description
total	total	number	0	Total number of items across all pages.
pageIndex	page-index	number	0	Current 0-indexed page.
pageSize	page-size	number	10	Items per page.
pageSizeOptions	—	number[]	[10, 20, 50, 100]	Options offered by the rows-per-page selector.
siblingCount	sibling-count	number	1	Maximum page buttons shown on each side of the current page (auto-reduced to fit the container width).
boundaryCount	boundary-count	number	1	Page buttons pinned at each edge.
showEdges	show-edges	boolean	false	Render First / Last jump arrows.
showPageSize	show-page-size	boolean	false	Render the rows-per-page selector.
showTotal	show-total	boolean	false	Render the "1–10 of 100" range label.
compact	compact	boolean	false	Force the compact "Page X of Y" + arrows layout at all widths (narrow containers collapse to it automatically even when unset).
size	size	'small' | 'medium' | 'large'	'medium'	Size variant, propagated to inner controls.
disabled	disabled	boolean	false	Disable the whole control.
label	label	string	'Pagination'	Accessible label for the navigation landmark.
strings	—	Partial<PaginationStrings>	{}	The built-in strings — arrow and page-button names, the rows-per-page label, the compact status and the range label. Only the keys set replace the English defaults (DEFAULT_PAGINATION_STRINGS); a template keeps its {placeholders}. Use for internationalization.
pageCount	—	number	—	Total page count (>= 1).

Events

Event	Detail	Description
change	—	Fired on any page or size change. Detail: PaginationChangeDetail ({ pageIndex, pageSize, reason }). When the size changes, pageIndex resets to 0.

CSS Parts

Part	Description
base	The nav landmark element.
list	The page-button row (ul).
page	A page-number button.
page-current	The current page button (also carries aria-current).
prev	The previous-page arrow button.
next	The next-page arrow button.
first	The first-page arrow button.
last	The last-page arrow button.
ellipsis	A collapsed-gap ellipsis.
info	The range/total label container.
size-select	The rows-per-page select.

CSS Custom Properties

The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.

Property	Default	Description
--hy-pagination-gap-row-nav-md-inline	var(--hy-gap-row-nav-md-inline)	Gap between controls.
--hy-pagination-gap-row-nav-sm-inline	var(--hy-gap-row-nav-sm-inline)	Gap between controls.
--hy-pagination-gap-row-nav-lg-inline	var(--hy-gap-row-nav-lg-inline)	Gap between controls.
--hy-pagination-control-height-md	var(--hy-control-height-md)	Square size of page / arrow buttons.
--hy-pagination-control-height-sm	var(--hy-control-height-sm)	Square size of page / arrow buttons.
--hy-pagination-control-height-lg	var(--hy-control-height-lg)	Square size of page / arrow buttons.
--hy-pagination-radius-action-md	var(--hy-radius-action-md)	Corner radius of the buttons — the action radius hy-button reads, in every size.
--hy-pagination-size-select-width	—	Control width of the page-size select (fits its widest option under any picker; a per-instance layout constraint). Default: 6rem