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.

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

Slots

Slot	Description
info	Custom range/total content, replacing the built-in show-total label.

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

Property	Description
--hy-pagination-gap	Gap between controls.
--hy-pagination-button-size	Square size of page / arrow buttons.
--hy-pagination-radius	Corner radius of the buttons.