Pagination
Data pagination navigation with page-number ellipsis, prev/next flipping, configurable sibling page count, total display, page-size switching and quick jump.
Basic usage
Basic usage
Page-number ellipsis
Ellipsis for many pages
Sibling page count
siblings control
Page-number cap
pager-count page-number cap
When the cap is exceeded, the window shrinks centered on the current page, leaving at least 2 pages on each side of an ellipsis (first/last pages always reachable); values below the minimum 5 fall back to 5 with a console warning.
Total count
show-total displays the total
Page-size switching
page-sizes dropdown
Switching the page size resets to page 1 and fires oas-change with detail: { page: 1, pageSize }.
Page-size switch threshold
total-boundary controls the page-size switcher
With total-boundary set, the page-size dropdown renders only when total exceeds the threshold; without it, the current behavior is kept (dropdown shows whenever page-sizes is set).
Quick jump
show-jumper jump to a page
Enter a page number and press Enter to jump (out-of-range values are clamped to the valid range), firing oas-change with detail: { page, pageSize }.
Combined usage
Total + page-size + quick jump
Flip event
oas-change event
Disabled state
disabled disables everything
Sizes
size five tiers (xs / sm / md / lg / xl)
Defaults to md; invalid values fall back to md with a console warning.
Simple mode
simple minimal form
The simple form renders only the prev/next buttons and a "current / total pages" text; it is mutually exclusive with the page-number ellipsis algorithm (simple wins).
Unknown-total form
show-more for unknown totals
show-more targets unknown-total scenarios: no page-number sequence or total text, just the three buttons; show-jumper / page-sizes / hide-on-single do not apply (no page-count concept).
First / last pages
show-edges first/last buttons
Hide on single page
hide-on-single hides the component
Custom icons
prev-icon / next-icon slots
Providing slot="prev-icon" / slot="next-icon" content replaces the default ‹ / › arrows.
Custom total
total slot
Providing slot="total" content replaces the built-in "Total N" text; the show-total boolean remains compatible (built-in text shown without slot content).
Flip interception
oas-before-change veto
oas-before-change fires before a page change/jump with detail: { page }; the host can call preventDefault() to cancel the change (this demo vetoes jumping to page 4). Page-size switching is not intercepted.
Controlled mode
controlled current
External buttons set the current attribute directly to drive the view (out-of-range values are clamped); the component's own flips fire oas-change and write back the attribute.
Edge cases
Single page / first-last disabled
Link mode
href-template renders links
With href-template (containing the {page} placeholder) set, page/prev/next/first/last are rendered as <a href> with {page} replaced by the target page; target is passed through to <a target>. When disabled they degrade to non-clickable spans. Clicking still fires oas-change; vetoing oas-before-change also prevents native navigation.
Responsive
responsive switches to minimal on narrow screens
Clickable ellipsis
ellipsis jumps pages
Ellipsis is a clickable button: clicking jumps siblings + 1 pages in that direction (subject to the oas-before-change veto and clamped to the valid range); aria-label via i18n (Jump forward/Jump backward).
Custom page-number content
page-item slot template
Put template content containing the {page} placeholder; the component clones it into every page-number button and replaces the {page} text with the actual page number (textContent-only replacement, injection-safe). Without the slot, buttons show plain page numbers. prev/next/first/last are unaffected.
API
oas-pagination
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
current | Current page (controlled; flipping updates this attribute) | string | 1 |
disabled | Disables everything: all page buttons with aria-disabled, plus the page-size dropdown and jumper input | boolean | — |
hide-on-single | Hides the whole component when there is a single page (pageCount ≤ 1) | boolean | — |
href-template | Link mode: renders page/prev/next/first/last as <a href> (the {page} placeholder is replaced with the target page); middle/right-click and opening in a new tab work natively; degrades to a non-clickable span when disabled | string | — |
page-size | Records per page | string | 10 |
page-sizes | Page-size dropdown options (JSON array), e.g. [10,20,50]; switching resets to page 1 | string | — |
pager-count | Maximum number of page-number buttons (excluding prev/next/first/last), default 9; when exceeded, the window shrinks centered on the current page (at least 2 pages on each side of an ellipsis, first/last reachable); values below the minimum 5 fall back to 5 with a warning | string | 9 |
responsive | Responsive: renders in the simple minimal form automatically when the component is narrower than 640px (ResizeObserver on the host; restores when wide enough); equivalent to explicit simple | boolean | — |
show-edges | Shows first/last double-arrow buttons (« »), disabled at the boundaries; aria-label via i18n | boolean | — |
show-jumper | Shows a quick-jump input "Jump to page" (Enter to jump, out-of-range clamped) | boolean | — |
show-more | Unknown-total form: when total ≤ 0 renders Previous / More / Next (More is a non-clickable status indicator, styled like a page button but muted; prev/next flip current ± 1 and fire oas-change); ignored when total > 0 (normal page numbers); show-jumper / page-sizes / hide-on-single do not apply | boolean | — |
show-total | Shows the total text "Total {total}" | boolean | — |
siblings | Number of page numbers shown on each side of the current page | string | 1 |
simple | Minimal form: only prev/next buttons and a "current / total pages" text; mutually exclusive with the page-number ellipsis algorithm (simple wins); show-jumper still applies | boolean | — |
size | Size tier: xs / small / medium (default) / large / xl; sm/md/lg are accepted aliases; invalid values fall back to medium with a console warning | string | medium |
target | Passthrough to <a target> (e.g. _blank) in link mode; only applies when href-template is set | string | — |
total | Total number of records | string | 0 |
total-boundary | Page-size switcher visibility threshold: when set, the page-size dropdown renders only when total exceeds the value (hidden when total ≤ threshold); unset keeps current behavior (dropdown shows whenever page-sizes is set) | string | — |
Events
| Event | Description |
|---|---|
oas-before-change | Fires before a page change/jump; preventDefault cancels the change (page-size switching is not intercepted); in link mode it also prevents native navigation |
oas-change | Flipping { page }; page-size switch { page: 1, pageSize }; quick jump { page, pageSize }, detail: { page } | { page: 1, pageSize } | { page, pageSize } |
Slots
| Name | Description |
|---|---|
next-icon | Icon slot for the next button; replaces the default › when present |
page-item | Custom page-number content slot: put template content containing the {page} placeholder (e.g. <span slot="page-item" hidden>Page {page}</span>); the component clones it into every page-number button and replaces the placeholder (textContent only, injection-safe); falls back to plain page numbers when absent; prev/next/first/last are unaffected |
prev-icon | Icon slot for the previous button; replaces the default ‹ when present |
total | Total text slot; replaces the built-in "Total N" text when present |
CSS Variables
| CSS Variable | Default |
|---|---|
--oas-pagination-font | var(--oas-font-size-md) |
--oas-pagination-height | var(--oas-control-height-md) |
Page numbers are omitted automatically when out of range, and the first/last flip buttons are disabled at the boundaries.