Pagination
Page navigation with first/last boundaries, sibling pages around the current page, and ellipses.
Import
Section titled “Import”<script> import Pagination from "@invisible-ui/svelte/Pagination.svelte";</script><script setup> import { Pagination } from "@invisible-ui/vue";</script>import { Pagination } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-pagination></ds-pagination>| Prop | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Current page. Controllable mirror: clicking a page updates it locally and reports through onPageChange; a later prop value overwrites the local choice (clamped to pageCount) without a callback. The other props keep their initial-value behaviour. |
pageCount * | number | — | |
siblingCount | number | 1 | |
boundaryCount | number | 1 | |
disabled | boolean | false | |
label | string | undefined | undefined | Accessible name for the nav. |
onPageChange | ((page: number) => void) | undefined | undefined | Called when the page changes. |
| Prop | Type | Default | Description |
|---|---|---|---|
modelValue | number | undefined | v-model value; takes precedence over page when bound. |
page | number | 1 | Current page (1-based). |
pageCount * | number | — | Total number of pages. |
siblingCount | number | 1 | Pages shown on each side of the current page. |
boundaryCount | number | 1 | Pages always shown at the start and end. |
disabled | boolean | false | |
label | string | undefined | Accessible name for the navigation landmark. Defaults to the catalog's "Pagination". |
onPageChange | (page: number) => void | undefined | Called whenever the page changes. |
| Event | Payload |
|---|---|
update:modelValue | page: number |
| Prop | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Initial (uncontrolled) or current (controlled) page, 1-based. A later prop, clamped to pageCount, overwrites the local choice without a report. |
pageCount * | number | — | Total number of pages. |
siblingCount | number | 1 | Pages shown on each side of the current page. |
boundaryCount | number | 1 | Pages always shown at the start and end. |
disabled | boolean | false | |
label | string | — | Accessible name for the navigation landmark. Defaults to the catalog's "Pagination". |
onPageChange | (page: number) => void | — | Called whenever the page changes. |
| Attribute | Reactive | Description |
|---|---|---|
page | yes | |
page-count * | yes | |
sibling-count | yes | |
boundary-count | yes | |
disabled | yes | |
label | yes | |
previous-label | yes | |
next-label | yes | |
page-label | yes |
Reactive attributes re-render the element when they change after the first render.
Emits: change (detail.page) after a user action changes the page.
Accessibility
Section titled “Accessibility”<nav>with a labelled list; the current page carriesaria-current="page".- In right-to-left text Left and Right swap, so the arrows keep following the reading direction; the page’s
diris read when a key is pressed, with or without a locale provider.
Example
Section titled “Example”<Pagination page={3} pageCount={10} onPageChange={(p) => (page = p)} />With Elements, use attributes for configuration and listen for the bubbling
change event. Its detail contains the committed page.
<ds-pagination page="3" page-count="10" label="Catalog pages"></ds-pagination>
<script type="module"> import "@invisible-ui/elements/define";
const pagination = document.querySelector("ds-pagination"); pagination.addEventListener("change", (event) => { pagination.page = event.detail.page; });</script>Use previous-label, next-label and page-label to localize the control.
The page-label value supports the {page} placeholder.
In React, the control names come from the provider’s catalog
(pagination.previous, pagination.next, pagination.page). When a press
disables Previous or Next, focus moves to the page that is now current:
<Pagination page={page} pageCount={10} onPageChange={setPage} />Themeable via --ds-pagination-*.