oks-uiPagination component
Pagination is a windowed page-number control for a list or table footer, with previous/next buttons and an optional "Showing X–Y of Z" summary (PaginationSummary).
Playground
Change a prop on the right and the preview updates. Switch to Code to copy what you see.
Recipes
Copy-paste patterns for the ways Pagination actually gets used — each one a real, self-contained example.
Page control
A windowed page-number control — pass the current page, the total pageCount, and an onChange to move between pages.
const [page, setPage] = useState(1);
<Pagination aria-label="Basic pagination" page={page} pageCount={12} onChange={setPage} />With a results summary
PaginationSummary prints a “Showing X–Y of Z” line — pair it with Pagination in a list or table footer.
<div className="flex items-center justify-between">
<PaginationSummary page={page} pageSize={20} total={438} />
<Pagination aria-label="Pagination with summary" page={page} pageCount={22} onChange={setPage} />
</div>Table footer
The typical composition: a summary on the left, page control on the right, beneath a table.
<footer className="flex items-center justify-between border-t pt-4">
<PaginationSummary page={page} pageSize={10} total={total} />
<Pagination
aria-label="Table pagination"
page={page}
pageCount={Math.ceil(total / 10)}
onChange={setPage}
/>
</footer>Example
<div className="flex items-center justify-between">
<PaginationSummary page={page} pageSize={20} total={438} />
<Pagination page={page} pageCount={22} onChange={setPage} />
</div>Props
The full public API for Pagination. Every prop is stable and intentionally typed.
Data
| Prop | Type | Default | Description |
|---|---|---|---|
| pageCount | number | — | Total pages. Or pass total + pageSize. |
| total / pageSize | number | — / 10 | Item count → derives pageCount. |
| page / defaultPage | number | — / 1 | Controlled / initial page (1-based). |
pageCount
number
default: —
Total pages. Or pass total + pageSize.
total / pageSize
number
default: — / 10
Item count → derives pageCount.
page / defaultPage
number
default: — / 1
Controlled / initial page (1-based).
Behavior & states
| Prop | Type | Default | Description |
|---|---|---|---|
| onChange | (page: number) => void | — | Fired on any page change. |
| isDisabled | boolean | false | Disable every button. |
| getItemAriaLabel | (type, page, isSelected) => string | — | Localise the button labels. |
onChange
(page: number) => void
default: —
Fired on any page change.
isDisabled
boolean
default: false
Disable every button.
getItemAriaLabel
(type, page, isSelected) => string
default: —
Localise the button labels.
Appearance
| Prop | Type | Default | Description |
|---|---|---|---|
| siblingCount | number | 1 | Pages shown either side of the current one. |
| boundaryCount | number | 1 | Pages always shown at each end. |
| showEdges | boolean | false | First / last jump buttons. |
| hideNavigation | boolean | false | Hide the prev / next arrows. |
| size | "sm" | "md" | "lg" | md | Control size. |
| variant | "solid" | "soft" | "bordered" | "ghost" | solid | Styles the selected page. Same vocabulary as Button/Chip. |
| color | "default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger" | primary | Selected-page color. |
| radius | "none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full" | md | Corner rounding of each page button. |
siblingCount
number
default: 1
Pages shown either side of the current one.
boundaryCount
number
default: 1
Pages always shown at each end.
showEdges
boolean
default: false
First / last jump buttons.
hideNavigation
boolean
default: false
Hide the prev / next arrows.
size
"sm" | "md" | "lg"
default: md
Control size.
variant
"solid" | "soft" | "bordered" | "ghost"
default: solid
Styles the selected page. Same vocabulary as Button/Chip.
color
"default" | "primary" | "secondary" | "info" | "success" | "warning" | "danger"
default: primary
Selected-page color.
radius
"none" | "xs" | "xs-sm" | "sm" | "md" | "lg" | "full"
default: md
Corner rounding of each page button.
Styling
| Prop | Type | Default | Description |
|---|---|---|---|
| classNames | { base?, list?, item?, page?, prev?, next?, ellipsis? } | — | Slot classes. |
classNames
{ base?, list?, item?, page?, prev?, next?, ellipsis? }
default: —
Slot classes.
Content
| Prop | Type | Default | Description |
|---|---|---|---|
| PaginationSummary | { page, pageSize, total, format? } | — | Renders "Showing X–Y of Z"; format(from, to, total) overrides the text. |
PaginationSummary
{ page, pageSize, total, format? }
default: —
Renders "Showing X–Y of Z"; format(from, to, total) overrides the text.
Accessibility
- Wrapped in `<nav aria-label="Pagination">`; the current page button has `aria-current="page"`.
- Previous/next buttons are disabled (not hidden) at the ends and keep an accessible name.
- The ellipsis is inert text, not a focusable control.
