Pagination
Pagination provides basic previous, next, and page links without owning data or page state.
Overview and decision boundary
Use Pagination when the product already has page URLs and needs basic previous, next, and page navigation.
Do not add page calculation, data fetching, or table state management to Pagination.
Preview
import * as React from 'react';import { Pagination } from '@nerio-ui/ui';const AppLink = React.forwardRef<HTMLAnchorElement, React.AnchorHTMLAttributes<HTMLAnchorElement>>(function AppLink(props, ref) { return <a ref={ref} data-router-link="" {...props} />;});<Pagination previousHref="/docs/page/1" nextHref="/docs/page/3" pages={[{ key: '1', label: '1', href: '/docs/page/1' }, { key: '2', label: '2', href: '/docs/page/2', current: true, render: <AppLink href="#" /> }, { key: '3', label: '3', href: '/docs/page/3' }]} />Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm dlx nerio add paginationimport * as React from 'react';import { Pagination } from '@nerio-ui/ui';Usage
import * as React from 'react';import { Pagination } from '@nerio-ui/ui';const AppLink = React.forwardRef<HTMLAnchorElement, React.AnchorHTMLAttributes<HTMLAnchorElement>>(function AppLink(props, ref) { return <a ref={ref} data-router-link="" {...props} />;});<Pagination previousHref="/docs/page/1" nextHref="/docs/page/3" pages={[{ key: '1', label: '1', href: '/docs/page/1' }, { key: '2', label: '2', href: '/docs/page/2', current: true, render: <AppLink href="#" /> }, { key: '3', label: '3', href: '/docs/page/3' }]} />Variants
| Variant | Purpose |
|---|---|
Default | Link-based pagination with no client state. |
Anatomy
| Slot | Purpose |
|---|---|
root | Nav landmark with aria-label="Pagination" by default. |
list | List of page navigation controls. |
item | Item slot exposed through data-slot="item". |
previous | Previous-page link or non-focusable disabled text. |
page | Page link with optional current state. |
ellipsis | Ellipsis slot exposed through data-slot="ellipsis". |
next | Next-page link or non-focusable disabled text. |
States
| State | Purpose |
|---|---|
Current | Current links, buttons, router elements, and static pages use aria-current="page" plus the same stronger visual treatment. |
Disabled | Unavailable previous or next controls are not focusable. |
Focus | Links use the shared Nerio focus ring. |
Motion
- hover
- focus
Accessibility
- Renders a nav landmark with aria-label="Pagination" by default.
- Marks the current page with aria-current="page".
- Current pages keep the same data-current visual hook whether they render as links, buttons, router elements, disabled text, or static text.
- Disabled controls render as non-focusable text with aria-disabled; onSelect takes precedence over href when both are supplied.
- Page, previous, and next render elements support router adapters while preserving href, data-slot, current-page state, and accessible labels.
- Visible labels carry state; color is not the only indicator.
API
| Prop | Purpose |
|---|---|
pages | Array of page labels, hrefs, current flags, optional disabled states, and optional router render elements. |
previousHref / nextHref | When omitted, the control renders disabled and is not focusable. |
previousLabel / nextLabel | Visible labels for the boundary controls. |
className | Extends the nav root without replacing tokenized defaults. |
Implementation contract
| Contract | Value |
|---|---|
Registry item | pagination installs 5 source files into the configured components directory. |
Base UI | No interactive primitive required. |
Registry dependencies | None. |
Package dependencies | clsx, react, tailwind-merge, tailwindcss |
Styling contract
| Contract | Value |
|---|---|
Authoring | Complete, statically detectable Tailwind CSS v4 recipes own component visuals. |
Values | Semantic and component --n-* variables remain the canonical customization layer. |
Overrides | Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically. |
Residual CSS | Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer. |
Design notes
- Use Pagination when the product already has page URLs and needs basic previous, next, and page navigation.
Do / do not
Do
Use with server-rendered list pages, docs archives, and simple result sets.
Do not
Do not add page calculation, data fetching, or table state management to Pagination.
Related components
Tokens
These are the primary customization points. Override semantic or component tokens instead of changing component source.
| Token | Purpose |
|---|---|
--n-pagination-gap | Public customization point for this component contract. |
--n-pagination-item-size | Public customization point for this component contract. |
--n-pagination-control-padding-inline | Public customization point for this component contract. |
--n-pagination-radius | Public customization point for this component contract. |
--n-pagination-background | Public customization point for this component contract. |
--n-pagination-background-hover | Public customization point for this component contract. |
--n-pagination-background-current | Public customization point for this component contract. |
--n-pagination-border-width | Public customization point for this component contract. |
--n-pagination-border | Public customization point for this component contract. |
--n-pagination-border-current | Public customization point for this component contract. |
--n-pagination-foreground | Public customization point for this component contract. |
--n-pagination-foreground-hover | Public customization point for this component contract. |
--n-pagination-foreground-current | Public customization point for this component contract. |
--n-pagination-shadow | Public customization point for this component contract. |
--n-pagination-shadow-current | Public customization point for this component contract. |
--n-motion-hover-duration | Public customization point for this component contract. |
--n-motion-hover-easing | Public customization point for this component contract. |
--n-motion-focus-duration | Public customization point for this component contract. |
--n-motion-focus-easing | Public customization point for this component contract. |
--n-focus-ring | Public customization point for this component contract. |