Pagination#
Component <neo-pagination> is adaptive page navigation. Set page and pages attributes and the host builds the Prev / boundary / window / boundary / Next chips, flags the current page with aria-current="page", and dispatches neo-pagination-change on click. A ResizeObserver shrinks the sibling window first, then the boundary count, until the chips fit on a single row.
The selected state's markup and its scoped CSS. The CSS is wrapped in <style>@scope { ... }</style> and applies to the preview only. Edits change the preview above, applied live while Sync is on, or when you click Patch or Replace. Patch morphs the preview; Replace swaps it outright.
Signals
Datastar signals declared in the selected state's markup. Change a value to drive the preview, applied live while Sync is on, or when you click Patch.
Reference#
| Name | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Active page (1-indexed). Two-way bind via data-attr:page data-on:neo-pagination-change. |
pages | number | 1 | Total page count. page is clamped to [1, pages] on every render. |
sibling-count | number | 1 | Pages shown on each side of the active one. Increase to make ±N navigation cheaper; the adapt loop shrinks this first when the row runs out of room. |
boundary-count | number | 1 | Pages pinned at the start and end of the run. The adapt loop shrinks it after the sibling window has bottomed out at 0. |
disabled | boolean | false | Greys every chip and ignores clicks. Useful while a parent dataset is still loading. |
aria-label | string | "Pagination" | Set on the host's role="navigation" so screen readers announce the landmark. |
| Name | Description |
|---|---|
template[data-neo-pagination-prev] | Inner HTML of the prev button. Captured once on connect from a <template> child; the kit re-uses it on every render. Default (no template) is a single chevron-left icon (icon-only button). An empty template (<template data-neo-pagination-prev></template>) opts out of the prev button entirely. |
template[data-neo-pagination-next] | Same as the prev slot, on the right; default is chevron-right, empty opts out. |
| Name | Detail | Bubbles | Description |
|---|---|---|---|
neo-pagination-change | { page: number } | yes | Fires when the user picks a chip or clicks prev / next. page is the new active page; the host has already reflected page= by the time the event dispatches. |
| Name | Default | Description |
|---|---|---|
--neo-pagination-gap | calc(var(--page-spacing, 0.25rem) * 1) | Gap between chips. |
--neo-pagination-page-min | 2.25rem | Minimum width and height of a page chip. |
--neo-pagination-active-bg | var(--accent, currentColor) | Background of the active page chip. |
--neo-pagination-active-color | var(--accent-fg, var(--page-bg, #fff)) | Text color of the active page chip. |
--neo-pagination-active-hover-bg | color-mix(in srgb, var(--neo-pagination-active-bg), #000 12%) | Active chip background on hover. |
--neo-pagination-active-active-bg | color-mix(in srgb, var(--neo-pagination-active-hover-bg), #000 8%) | Active chip background while pressed. |
Examples#
Sibling count = 2#
sibling-count="2" reveals two neighbours on each side of the active page rather than one. Useful when users frequently jump ±2 pages and a single neighbour reads as too tight.
Boundary count = 2#
With boundary-count="2" the first and last two pages always render, handy for tables where users habitually jump to "page 1 / 2" or "second-to-last / last".
First page#
When the current page sits at or near the boundary, the matching ellipsis collapses and the window snaps flush against the edge run.
Last page#
Short run#
With fewer pages than the configured window plus boundary, the host lays out every page with no ellipses.
Custom prev / next slots#
The host exposes two <template> slots, [data-neo-pagination-prev] and [data-neo-pagination-next], whose inner HTML becomes the body of the prev / next buttons. Default content is a single chevron icon, so a bare host renders as icon-only.
No prev / next buttons#
Pass a <template data-neo-pagination-prev> / <template data-neo-pagination-next> with no children and the matching button is omitted entirely: pure page chips, no prev / next rail. Useful when the dataset's prev / next is wired elsewhere (keyboard shortcut, sidebar nav).
Disabled#
disabled greys every chip and ignores clicks. Use it while a parent dataset is loading.