Skip to content
Shaken UI
Sign in

Pagination

Save

Page 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 pagination

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add pagination --dry-run

Usage

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

PropTypeDefaultDescription
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 hrefstring—Renders an <a>. Without href (and without render) the control is a <button> for onClick paging.
PaginationLink isActivebooleanfalseMarks the current page with aria-current="page", a selected tint, and a hairline ring.
PaginationLink disabledbooleanfalseKeeps the control in place but inert. Links drop their href and set aria-disabled; buttons are disabled.
PaginationLink renderReactElement—Your router's link, for example render={<Link href="?page=4" />}.
PaginationPrevious / PaginationNext labelstring"Previous" / "Next"Visible text beside the arrow. Below 480px only the arrow shows; the text stays as the accessible name.
PaginationEllipsisComponentProps<"span">—Marks skipped pages. Hidden from assistive technology.
PaginationCompact page / pageCountnumber—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.tsxShow
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>
  );
}