Pagination

• Type: Component (data)
• Access: Free, open source
• Page: https://ui.xzero.co.uk/components/pagination
• Markdown: https://ui.xzero.co.uk/components/pagination/markdown
• Registry item: https://mcp.xzero.co.uk/r/pagination.json
• Source file: registry/components/pagination/pagination.tsx
• Dependencies: motion, lucide-react
• Keywords: data, navigation, react pagination, pagination component, page numbers, table pagination, animated pagination, next previous pages

When to use

• Paged server results and long tables.
• Lists where the page should live in the URL or state and fetch on change.

When not to use

• Use carousel for browsing slides.
• Use timeline with maxHeight for a scrolling feed instead of pages.

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui/pagination

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { useState } from "react";
import { Pagination } from "@/components/xzero/pagination/pagination";

export function Results() {
  const [page, setPage] = useState(1);
  return <Pagination page={page} pageCount={12} onPageChange={setPage} />;
}

API reference

Pagination

Previous and next buttons around a sliding five page window with a traveling current page mark.

Prop	Type	Default	Description
page (required)	number	–	Current page, 1-based. Clamped to the range.
pageCount (required)	number	–	Total pages. Zero renders an empty nav.
onPageChange (required)	(page: number) => void	–	Called with the requested page.
label	string	"Pagination"	Accessible name for the nav landmark.

Keyboard interactions

Keys	Action
Tab	Moves between the previous, page, and next buttons.
Enter / Space	Goes to that page.

Accessibility

• Renders a nav landmark with the label as its name.
• Page buttons are labelled "Page 3" and the current one has aria-current="page".
• Previous and next are disabled at the ends and carry aria-labels.

Motion

• The current page mark springs to the selected button.
• When the window shifts, numbers slide like a belt by the number of slots moved.
• Reduced motion jumps the mark and swaps numbers without sliding.

Responsive behavior

• It always shows a five page window plus arrows, so it stays the same width on any screen.
• The row wraps if its container is narrower than the buttons, and the current mark re-measures on resize.

Performance

• Only five page buttons render regardless of pageCount; one ResizeObserver repositions the current mark.

Notes for AI

• Use for paged server results and long tables. Use carousel for browsing slides.
• It is fully controlled: keep page in state or the URL and fetch on onPageChange.

Related

• Sortable data table: Compare structured records with sortable columns.
• Filter toolbar: Keep collection filters close and easy to reset.
• Carousel: Browse a row of slides by dragging, flicking, or arrowing through them.

Also in navigation

• Tabs: Switch between related content in the same context.
• Breadcrumb: Show where a page sits in a hierarchy.
• Mega menu morph: A site header whose menus share one floating panel. Moving between sections morphs its size, slides the next menu in from that side and glides the caret under the new trigger, with hover intent, a safe triangle and an accordion sheet on narrow screens.
• Table of contents progress: A table of contents that reads along with you: a line bends through the nested headings, fills as you scroll, and carries a marker to the current section, with smooth jumps and a time-left countdown.

Guidance for AI tools

Pagination: Move through a long collection with clear bounds. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt