Skip to main content

Pagination

Stable

Page navigation control with configurable sibling count, optional first/last buttons, and full ARIA landmark pattern. Current page receives aria-current='page'. Previous/Next/First/Last buttons have descriptive aria-labels.

NavigationVhyxSeal

Interactive example

10-page result set — click to navigate

Import

tsx
import { Pagination } from '@vhyxui/react'

Variants

With first and last page buttons
siblingCount={2} — wider page window
Without previous and next buttons

Sizes

sm, md, lg

Props

PropTypeDefaultDescription
pagenumber—Current active page (1-based). Required.
pageCountnumber—Total number of pages. Required.
onPageChange(page: number) => void—Called when the user navigates to a new page. Required.
siblingCountnumber1Number of sibling pages shown on each side of the current page.
showFirstLastbooleanfalseShow first and last page buttons.
showPrevNextbooleantrueShow previous and next page buttons.
size'sm' | 'md' | 'lg''md'Size of the pagination buttons.
contractPartial<ComponentContract>—VhyxSeal contract override.

Accessibility

  • ✓ Renders as <nav aria-label="Pagination"> — a navigable landmark.
  • ✓ Current page button gets aria-current="page" per ARIA spec.
  • ✓ Previous/Next buttons have aria-label="Previous page" / aria-label="Next page".
  • ✓ First/Last buttons have aria-label="First page" / aria-label="Last page".
  • ✓ Disabled buttons (e.g. Previous on page 1) have aria-disabled="true".
  • ✓ Ellipsis indicators are aria-hidden="true" — decorative only.

Keyboard navigation

KeyAction
TabMove focus through pagination buttons in order.
Shift + TabMove focus backwards through pagination buttons.
EnterorSpaceActivate the focused page button.

Agent contract

Default VhyxSeal contract shipped with every Pagination.

Default contract
{
  "type": "navigation",
  "intent": "navigate-page",
  "description": "Navigates between pages of a paginated data set",
  "requires": [],
  "requiredPermissions": [],
  "consequence": "Changes the visible page of the data set — no data mutation",
  "affects": [
    "view"
  ],
  "reversible": true,
  "safetyLevel": "low",
  "requiresConfirmation": false,
  "destructive": false,
  "contractVersion": "0.0.1",
  "fingerprint": "vhyxs_6fc4415a"
}

Theming

Override these CSS tokens to theme Pagination.

--vhyx-color-surfaceButton background
--vhyx-color-accentActive page background
--vhyx-color-text-on-accentActive page text color
--vhyx-color-borderButton border
--vhyx-radius-mdButton border radius
--vhyx-size-sm / md / lgButton height per size
--vhyx-duration-fastHover transition duration

Examples

Search results — large dataset

Showing results 1–10 of 2,470

247 pages with first/last buttons

Controlled pagination

tsx
const [page, setPage] = useState(1);

// Fetch data when page changes
useEffect(() => {
  fetchData({ page, perPage: 20 });
}, [page]);

<Pagination
  page={page}
  pageCount={Math.ceil(totalItems / 20)}
  onPageChange={setPage}
  showFirstLast
/>