Pagination
Page numbers with smart gaps and a pill that glides to the current page.
- Category: Navigation
- Licence: Free, MIT
- Built with: React 19, Tailwind CSS 4, Motion
- Dependencies: motion, clsx, tailwind-merge
Examples
Pagination
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
page / defaultPage | number | — | |
onPageChange | (page: number) => void | — | |
total | number | — | |
siblings | number | 1 |
About Pagination
Pagination shows page numbers with smart gaps for long ranges and a pill that glides to the current page. It handles first, last and sibling pages so the control stays the same width.
Pagination is a navigation component for React 19, styled with Tailwind CSS 4 and animated with Motion. It drops into Next.js, Vite, Remix or Astro through the shadcn CLI as a single file you own.
When to use Pagination
- Search results and listings.
- Tables and admin views.
- Blog and article archives.
- Galleries split into pages.
How it works
siblings sets how many pages show around the current one, and gaps collapse the rest. The pill is a shared layout element, and the nav marks the current page with aria-current for screen readers.
Links and buttons keep their roles, arrow keys move where a group is expected, the current item is marked with aria-current, and focus is always visible. With prefers-reduced-motion on, it holds still or settles instantly instead of animating.
Customizing Pagination
Every prop is documented in the API reference above with its type and default. The ones you will reach for first are listed here.
The Customize panel next to the preview lets you change total, siblings live, and the Code tab updates to match, so the snippet you copy already carries your values.
- page / defaultPage (number).
- total (number).
- siblings (number, default 1).
Goes well with Pagination
These navigation pieces share its tokens and motion language, so they sit together on one page without clashing.
- Tabs: Animated React tabs with a gliding indicator and panels that slide the way you travel
- Breadcrumb: An animated React breadcrumb that folds long trails and unfolds them on click
- Sidebar: A collapsible React app sidebar with spring width, fading labels and an active marker
- Steps: Animated React steps for multi-step flows: filling connectors and drawn checks
- Dropdown Menu: An animated React dropdown menu with icons, shortcuts, checkboxes and keyboard control
Install Pagination
npx shadcn@latest add https://charcoalui.com/r/pagination.jsonPagination is free and MIT licensed. The command copies pagination.tsx into components/ui and installs clsx, tailwind-merge; you can also copy the source from the Code tab by hand.
It pairs well with Split Flap, a Pro piece: Airport departure board: every cell flips through the drum until it lands on its letter.
Frequently asked questions
- How do I install Pagination?
- Run npx shadcn@latest add https://charcoalui.com/r/pagination.json. The shadcn CLI copies pagination.tsx into components/ui and installs motion, clsx, tailwind-merge. You can also copy the source from this page by hand.
- Is Pagination free for commercial use?
- Yes. Pagination is MIT licensed: use it in any personal or commercial project and change it however you like.
- Does Pagination work with Next.js?
- Yes. It is a client component for React 19 styled with Tailwind CSS 4, so it works in the Next.js App Router and Pages Router, Vite, Remix and Astro.
- Can an AI coding agent install Pagination?
- Yes. Connect the Charcoal UI MCP server (https://charcoalui.com/mcp) to Claude Code, Cursor or any MCP client; get_component returns Pagination's props and source and get_install_command returns the exact command.