Pagination

Basic

A flexible pagination component for navigating paged data sets. Features smart ellipsis truncation, previous/next buttons, configurable sibling counts, and a compact variant.

<Pagination totalPages={20} defaultPage={5} /><Pagination totalPages={10} defaultPage={1} variant="compact" />

Installation

Install the component via the CLI in one command.

npx @work-rjkashyap/unified-ui add pagination

pnpm dlx @work-rjkashyap/unified-ui add pagination

npx @work-rjkashyap/unified-ui add pagination

bunx @work-rjkashyap/unified-ui add pagination

Or install the full package

Use this approach if you prefer to install the entire design system as a dependency instead of copying individual components.

npm install @work-rjkashyap/unified-ui

pnpm add @work-rjkashyap/unified-ui

yarn add @work-rjkashyap/unified-ui

bun add @work-rjkashyap/unified-ui

Anatomy

import {
	Pagination,
	Table,
	TableHeader,
	TableBody,
	TableRow,
	TableHead,
	TableCell,
} from "@work-rjkashyap/unified-ui";

Basic Usage

The Pagination component renders page number buttons with smart ellipsis truncation for large page counts. Previous and Next buttons are automatically disabled at the boundaries.

<Pagination totalPages={20} />

Controlled

Use page and onPageChange for controlled pagination state.

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

<Pagination
  page={page}
  totalPages={20}
  onPageChange={setPage}
/>

<p>Current page: {page}</p>

Uncontrolled

Use defaultPage to set the initial page without controlling state externally. The component manages its own internal state.

<Pagination totalPages={20} defaultPage={5} />

Variants

Default

The standard pagination with individual page number buttons, ellipsis, and prev/next controls.

<Pagination totalPages={20} defaultPage={7} />

Compact

A minimal "Page X of Y" display with just the prev/next buttons. Ideal for mobile or space-constrained layouts.

<Pagination totalPages={10} defaultPage={3} variant="compact" />

Sizes

Two sizes are available for different density needs.

<Pagination totalPages={10} size="sm" />  {/* Compact buttons */}<Pagination totalPages={10} size="md" />  {/* Default size */}

Smart Ellipsis

The pagination component uses a smart truncation algorithm that shows:

• The first and last page numbers (boundary pages)
• A configurable number of sibling pages around the current page
• Ellipsis (…) indicators when pages are skipped

{/* Near the start — no left ellipsis */}<Pagination totalPages={20} defaultPage={1} />{/* In the middle — both ellipses visible */}<Pagination totalPages={20} defaultPage={10} />{/* Near the end — no right ellipsis */}<Pagination totalPages={20} defaultPage={20} />

Sibling and Boundary Count

Configure how many sibling pages appear around the current page and how many boundary pages appear at the edges.

{
	/* Default: 1 sibling on each side */
}
<Pagination totalPages={50} defaultPage={25} />;

{
	/* More siblings for wider navigation */
}
<Pagination totalPages={50} defaultPage={25} siblingCount={2} />;

{
	/* More boundary pages */
}
<Pagination totalPages={50} defaultPage={25} boundaryCount={2} />;

Disabled State

The previous button is automatically disabled on page 1, and the next button is disabled on the last page. You can also disable the entire component.

{
	/* Auto-disabled at boundaries */
}
<Pagination totalPages={10} defaultPage={1} />;

{
	/* Fully disabled */
}
<Pagination totalPages={10} defaultPage={5} disabled />;

Small Page Counts

When the total page count is small enough to show all pages, no ellipsis is rendered.

<Pagination totalPages={1} />   {/* Just "1" — prev/next disabled */}<Pagination totalPages={3} />   {/* "1 2 3" — no ellipsis needed */}<Pagination totalPages={5} />   {/* "1 2 3 4 5" — all visible */}

Table Integration

A common pattern pairing pagination with a data table.

import {
	Table,
	TableHeader,
	TableBody,
	TableRow,
	TableHead,
	TableCell,
	Pagination,
} from "@work-rjkashyap/unified-ui";

function DataTable({ data, pageSize = 10 }) {
	const [page, setPage] = useState(1);
	const totalPages = Math.ceil(data.length / pageSize);
	const pageData = data.slice((page - 1) * pageSize, page * pageSize);

	return (
		<div className="flex flex-col gap-4">
			<Table>
				<TableHeader>
					<TableRow>
						<TableHead>Name</TableHead>
						<TableHead>Email</TableHead>
						<TableHead align="right">Role</TableHead>
					</TableRow>
				</TableHeader>
				<TableBody>
					{pageData.map((row) => (
						<TableRow key={row.id}>
							<TableCell>{row.name}</TableCell>
							<TableCell>{row.email}</TableCell>
							<TableCell align="right">{row.role}</TableCell>
						</TableRow>
					))}
				</TableBody>
			</Table>
			<div className="flex justify-center">
				<Pagination
					page={page}
					totalPages={totalPages}
					onPageChange={setPage}
				/>
			</div>
		</div>
	);
}

Compact Variant with Info

Combine the compact variant with additional page info for a mobile-friendly layout.

<div className="flex items-center justify-between w-full">
	<p className="text-sm text-muted-foreground">
		Showing {startItem}–{endItem} of {totalItems}
	</p>
	<Pagination
		page={page}
		totalPages={totalPages}
		onPageChange={setPage}
		variant="compact"
		size="sm"
	/>
</div>

Props

Accessibility

• Semantic markup — Renders as <nav> with aria-label="Pagination".
• Current page — The active page button has aria-current="page" so screen readers announce which page is selected.
• Disabled buttons — Previous/Next buttons at the boundaries use aria-disabled="true" and are not focusable.
• Page labels — Each page button has an accessible label like "Go to page 5" for screen readers.
• Ellipsis — Rendered as <span> with aria-hidden="true" since they're purely visual.
• Focus ring — Visible on keyboard navigation via focus-visible with the compact focus ring utility.
• Keyboard navigation — All buttons are standard <button> elements, navigable with Tab and activated with Enter or Space.
• The component does not trap focus — it participates in the normal tab order.

Design Tokens