Pagination
SavePage controls with previous and next, page numbers that collapse into ellipses, and a compact "Page 3 of 12" variant, as links or buttons.
- Category
- Navigation
- Version
- 0.1.0
- Frameworks
- Next.js, Vite + React
- Styling
- Tailwind CSS v4
Preview
Pagination preview
Showing runs 76 to 100 of 293
deploy.log
Installation
npx @shakenui/cli add paginationReview the plan first. A dry run lists every file and package without changing anything:
npx @shakenui/cli add pagination --dry-runUsage
pagination-example.tsx
"use client";
import { useState } from "react";
import {
Pagination,
PaginationCompact,
PaginationEllipsis,
PaginationItem,
PaginationLink,
PaginationList,
PaginationNext,
PaginationPrevious,
paginationRange,
} from "@/components/shaken/ui/pagination";
const pageSize = 25;
const runCount = 293;
const pageCount = Math.ceil(runCount / pageSize);
export default function PaginationExample() {
const [page, setPage] = useState(4);
const [logPage, setLogPage] = useState(3);
const first = (page - 1) * pageSize + 1;
const last = Math.min(page * pageSize, runCount);
return (
<div className="flex w-full max-w-xl flex-col gap-8">
<div className="flex flex-col items-center gap-3">
<Pagination aria-label="Agent runs pages">
<PaginationList>
<PaginationItem>
<PaginationPrevious disabled={page === 1} onClick={() => setPage(page - 1)} />
</PaginationItem>
{paginationRange(page, pageCount).map((entry, index) =>
entry === "ellipsis" ? (
<PaginationItem key={`gap-${index}`}>
<PaginationEllipsis />
</PaginationItem>
) : (
<PaginationItem key={entry}>
<PaginationLink isActive={entry === page} aria-label={`Page ${entry}`} onClick={() => setPage(entry)}>
{entry}
</PaginationLink>
</PaginationItem>
),
)}
<PaginationItem>
<PaginationNext disabled={page === pageCount} onClick={() => setPage(page + 1)} />
</PaginationItem>
</PaginationList>
</Pagination>
<p className="text-xs text-zinc-500 tabular-nums">
Showing runs {first} to {last} of {runCount}
</p>
</div>
<div className="flex items-center justify-between gap-4 border-t border-zinc-950/[0.07] pt-4 dark:border-white/[0.08]">
<span className="font-mono text-xs text-zinc-500">deploy.log</span>
<Pagination aria-label="Log pages">
<PaginationCompact page={logPage} pageCount={12} onPageChange={setLogPage} />
</Pagination>
</div>
</div>
);
}API
| Prop | Type | Default | Description |
|---|---|---|---|
| paginationRange(page, pageCount, siblings?) | (number, number, number) => (number | "ellipsis")[] | — | Pages to render: first, last, the current page with siblings on each side, and ellipses for skipped runs. The length stays constant once there are enough pages, so controls do not jump. |
| PaginationLink href | string | — | Renders an <a>. Without href (and without render) the control is a <button> for onClick paging. |
| PaginationLink isActive | boolean | false | Marks the current page with aria-current="page", a selected tint, and a hairline ring. |
| PaginationLink disabled | boolean | false | Keeps the control in place but inert. Links drop their href and set aria-disabled; buttons are disabled. |
| PaginationLink render | ReactElement | — | Your router's link, for example render={<Link href="?page=4" />}. |
| PaginationPrevious / PaginationNext label | string | "Previous" / "Next" | Visible text beside the arrow. Below 480px only the arrow shows; the text stays as the accessible name. |
| PaginationEllipsis | ComponentProps<"span"> | — | Marks skipped pages. Hidden from assistive technology. |
| PaginationCompact page / pageCount | number | — | Current page (from 1) and total pages for the compact variant. |
| PaginationCompact onPageChange / getHref | (page) => void / (page) => string | — | Button paging, or link paging when getHref is set. renderLink wraps links in your router component. |
Accessibility
- Pagination renders a nav landmark named "Pagination"; rename it with aria-label when there is more than one.
- The current page has aria-current="page" and reads without color: a tint plus a hairline ring and stronger text.
- Page numbers rendered as buttons get an aria-label such as "Page 4" in the example, so the control is not announced as a bare number.
- Previous and Next keep their text as the accessible name when it is visually hidden on narrow screens.
- Disabled link controls have no href and set aria-disabled, so they stay in reading order but cannot be followed; disabled buttons use the disabled attribute.
- The compact variant's "Page 3 of 12" is a polite live region, so the new page is announced after an arrow is pressed.
- Controls have a visible focus ring and change only colors (150ms, removed with reduced motion).
Files
Installed into src/components/shaken, or components/shaken when the project has no src directory.
src/components/shaken/ui/pagination.tsxpagination- npm packages: @base-ui/react@^1.9.0React and Tailwind CSS v4 required
Source
The exact source the CLI installs, from /r/items/react/pagination/0.1.0.json.
ui/pagination.tsxShowHide
ui/pagination.tsx
"use client";
import { mergeProps } from "@base-ui/react/merge-props";
import { useRender } from "@base-ui/react/use-render";
import type { ComponentProps, MouseEvent, ReactElement } from "react";
function cx(...classes: (string | false | null | undefined)[]) {
return classes.filter(Boolean).join(" ");
}
/**
* The pages to show for `page` out of `pageCount`: always the first and last page, `siblings`
* pages on each side of the current one, and `"ellipsis"` where a run of pages is skipped.
* The result has a constant length once there are enough pages, so the controls never jump in width.
*/
export function paginationRange(page: number, pageCount: number, siblings = 1): (number | "ellipsis")[] {
const total = Math.max(1, Math.floor(pageCount));
const current = Math.min(Math.max(1, Math.floor(page)), total);
// first + last + current + siblings on each side + two ellipses
const slots = siblings * 2 + 5;
if (total <= slots) return Array.from({ length: total }, (_, index) => index + 1);
const range = (from: number, to: number) => Array.from({ length: to - from + 1 }, (_, index) => from + index);
const edgeCount = siblings * 2 + 3;
const showStartGap = current - siblings > 3;
const showEndGap = current + siblings < total - 2;
if (!showStartGap) return [...range(1, edgeCount), "ellipsis", total];
if (!showEndGap) return [1, "ellipsis", ...range(total - edgeCount + 1, total)];
return [1, "ellipsis", ...range(current - siblings, current + siblings), "ellipsis", total];
}
export interface PaginationProps extends ComponentProps<"nav"> {
/** Accessible name of the landmark. */
"aria-label"?: string;
}
/** The pagination landmark. Holds a `PaginationList`, or a `PaginationCompact`. */
export function Pagination({ "aria-label": label = "Pagination", className, ...props }: PaginationProps) {
return <nav aria-label={label} className={cx("flex", className)} {...props} />;
}
/** The row of page controls. */
export function PaginationList({ className, ...props }: ComponentProps<"ul">) {
return <ul className={cx("m-0 flex list-none items-center gap-1 p-0", className)} {...props} />;
}
/** Wraps one control in the list. */
export function PaginationItem({ className, ...props }: ComponentProps<"li">) {
return <li className={cx("flex", className)} {...props} />;
}
const control = cx(
"inline-flex h-8 min-w-8 items-center justify-center gap-1 rounded-lg px-2 text-sm font-medium tabular-nums no-underline select-none",
"text-zinc-600 dark:text-zinc-400",
"transition-[background-color,color,box-shadow] duration-150 ease-out motion-reduce:transition-none",
"hover:bg-zinc-950/[0.04] hover:text-zinc-950 dark:hover:bg-white/[0.06] dark:hover:text-white",
"focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500",
// The current page: selected tint plus a hairline ring, so it reads without color.
"aria-[current=page]:bg-zinc-950/[0.06] aria-[current=page]:text-zinc-950 aria-[current=page]:shadow-[inset_0_0_0_1px_rgb(9_9_11/0.1)]",
"dark:aria-[current=page]:bg-white/[0.09] dark:aria-[current=page]:text-white dark:aria-[current=page]:shadow-[inset_0_0_0_1px_rgb(255_255_255/0.14)]",
"aria-disabled:pointer-events-none aria-disabled:opacity-40 disabled:pointer-events-none disabled:opacity-40",
"[&_svg]:size-4 [&_svg]:shrink-0",
);
export interface PaginationLinkProps extends Omit<useRender.ComponentProps<"a">, "href"> {
/** Destination of the control. Without it the control renders a `<button>` for `onClick` paging. */
href?: string;
/** Marks the current page with `aria-current="page"`. */
isActive?: boolean;
/** Keeps the control in place but inert, for example Previous on the first page. */
disabled?: boolean;
}
/**
* A page number or arrow control. Renders an `<a>` when `href` is set and a `<button>` otherwise;
* pass `render={<Link href="…" />}` for your router. Disabled links drop their `href` and set
* `aria-disabled`, so they stay in the reading order without being followable.
*/
export function PaginationLink({ href, isActive = false, disabled = false, render, className, onClick, ...props }: PaginationLinkProps) {
const asLink = href !== undefined || render !== undefined;
const handleClick = (event: MouseEvent<HTMLAnchorElement>) => {
if (disabled) {
event.preventDefault();
return;
}
onClick?.(event);
};
return useRender({
defaultTagName: asLink ? "a" : "button",
render,
props: mergeProps<"a">(
{
className: cx(control, className),
"aria-current": isActive ? "page" : undefined,
...(asLink
? { href: disabled ? undefined : href, "aria-disabled": disabled || undefined, role: disabled ? "link" : undefined }
: ({ type: "button", disabled } as Record<string, unknown>)),
},
{ ...props, onClick: handleClick },
),
});
}
const chevronLeft = (
<svg aria-hidden="true" viewBox="0 0 16 16" fill="none">
<path d="M9.75 4.25 6 8l3.75 3.75" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
</svg>
);
const chevronRight = (
<svg aria-hidden="true" viewBox="0 0 16 16" fill="none">
<path d="M6.25 4.25 10 8l-3.75 3.75" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
</svg>
);
export interface PaginationStepProps extends PaginationLinkProps {
/** Visible text. Hidden below 480px wide, where only the arrow shows; it stays the accessible name. */
label?: string;
}
/** The control that goes back one page. */
export function PaginationPrevious({ label = "Previous", className, ...props }: PaginationStepProps) {
return (
<PaginationLink className={cx("pr-2.5 pl-1.5", className)} {...props}>
{chevronLeft}
<span className="max-[480px]:sr-only">{label}</span>
</PaginationLink>
);
}
/** The control that goes forward one page. */
export function PaginationNext({ label = "Next", className, ...props }: PaginationStepProps) {
return (
<PaginationLink className={cx("pr-1.5 pl-2.5", className)} {...props}>
<span className="max-[480px]:sr-only">{label}</span>
{chevronRight}
</PaginationLink>
);
}
/** Marks skipped pages. Hidden from assistive technology; the page numbers around it carry the meaning. */
export function PaginationEllipsis({ className, ...props }: ComponentProps<"span">) {
return (
<span
aria-hidden="true"
className={cx("inline-flex h-8 w-6 items-center justify-center pt-1.5 text-zinc-400 dark:text-zinc-600", className)}
{...props}
>
<svg viewBox="0 0 16 4" fill="currentColor" className="h-1 w-4">
<circle cx="2.5" cy="2" r="1.1" />
<circle cx="8" cy="2" r="1.1" />
<circle cx="13.5" cy="2" r="1.1" />
</svg>
</span>
);
}
export interface PaginationCompactProps extends Omit<ComponentProps<"div">, "children"> {
/** The current page, starting at 1. */
page: number;
/** Total number of pages. */
pageCount: number;
/** Called with the next page when an arrow is pressed. Use it for button paging. */
onPageChange?: (page: number) => void;
/** Builds a URL for a page. When set, the arrows render as links. */
getHref?: (page: number) => string;
/** Wraps each arrow link, for example `(href) => <Link href={href} />`. */
renderLink?: (href: string) => ReactElement;
/** Accessible names of the arrows. */
previousLabel?: string;
nextLabel?: string;
}
/**
* A compact pager for tight spaces: two arrows around "Page 3 of 12". The count is a polite live
* region, so screen readers hear the new page after an arrow is pressed.
*/
export function PaginationCompact({
page,
pageCount,
onPageChange,
getHref,
renderLink,
previousLabel = "Previous page",
nextLabel = "Next page",
className,
...props
}: PaginationCompactProps) {
const total = Math.max(1, pageCount);
const current = Math.min(Math.max(1, page), total);
const linkProps = (target: number) => {
const href = getHref?.(target);
return {
href,
render: href !== undefined && renderLink ? renderLink(href) : undefined,
onClick: onPageChange ? () => onPageChange(target) : undefined,
};
};
return (
<div className={cx("inline-flex items-center gap-1", className)} {...props}>
<PaginationLink aria-label={previousLabel} disabled={current <= 1} className="px-0" {...linkProps(current - 1)}>
{chevronLeft}
</PaginationLink>
<span aria-live="polite" className="min-w-[7.5rem] px-1 text-center text-sm text-zinc-500 tabular-nums dark:text-zinc-400">
Page <span className="font-medium text-zinc-950 dark:text-white">{current}</span> of {total}
</span>
<PaginationLink aria-label={nextLabel} disabled={current >= total} className="px-0" {...linkProps(current + 1)}>
{chevronRight}
</PaginationLink>
</div>
);
}