Skip to content
← Components

Pagination

Pagination for a useful, keyboard-friendly product interface.

Open ↗

Make it yours.

Install the editable source and its dependencies into your React + Tailwind project.

Scroll horizontally for long lines
pnpm dlx shadcn@4.0.8 add http://localhost:3000/r/pagination.json

Use it

Scroll horizontally for long lines
"use client";
import { Pagination } from "@/components/jez-ui/ui/pagination";

export default function Example() {
  return (
    <>
      <div className="w-full max-w-sm">
        <div className="mb-7">
          <h3 className="text-2xl tracking-tight">There is more to explore.</h3>
          <p className="mt-2 text-sm leading-relaxed text-muted-foreground">
            Browse the whole collection, at your own pace.
          </p>
        </div>
        <Pagination totalPages={8} />
      </div>
    </>
  );
}

Compose your own

These styled parts are included in the same install. Use children to build your layout; add className only when you want an override.

Scroll horizontally for long lines
import { Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis } from "@/components/jez-ui/ui/pagination";
Read the composition guide →

Props & types

Scroll horizontally for long lines
Omit<
  React.ComponentProps<"nav">,
  keyof {
    page?: number;
    defaultPage?: number;
    onPageChange?: (page: number) => void;
    children?: React.ReactNode;
    totalPages?: number;
    className?: string;
  }
> & {
  page?: number;
  defaultPage?: number;
  onPageChange?: (page: number) => void;
  children?: React.ReactNode;
  totalPages?: number;
  className?: string;
}

Source

View 4 source files

registry/ui/pagination.tsx

Scroll horizontally for long lines
"use client";
import * as React from "react";
import { cn } from "./utils";
import { Button } from "./button";
import { useControllable } from "./use-controllable";
export function Pagination({
  children,
  page,
  defaultPage = 1,
  onPageChange,
  totalPages = 1,
  className,
  ...rootProps
}: Omit<
  React.ComponentProps<"nav">,
  keyof {
    page?: number;
    defaultPage?: number;
    onPageChange?: (page: number) => void;
    children?: React.ReactNode;
    totalPages?: number;
    className?: string;
  }
> & {
  page?: number;
  defaultPage?: number;
  onPageChange?: (page: number) => void;
  children?: React.ReactNode;
  totalPages?: number;
  className?: string;
}) {
  const [current, setPage] = useControllable(page, defaultPage, onPageChange);
  return (
    <nav
      {...rootProps}
      aria-label="Pagination"
      className={cn("flex items-center gap-3", className)}
    >
      {children ?? (
        <>
          <Button
            variant="outline"
            disabled={current <= 1}
            onClick={() => setPage(current - 1)}
          >
            Previous
          </Button>
          <span aria-live="polite" className="text-sm">
            {current} / {Math.max(1, totalPages)}
          </span>
          <Button
            variant="outline"
            disabled={current >= totalPages}
            onClick={() => setPage(current + 1)}
          >
            Next
          </Button>
        </>
      )}
    </nav>
  );
}
export function PaginationContent({
  className,
  ...props
}: React.ComponentProps<"ul">) {
  return (
    <ul
      className={cn("flex list-none items-center gap-1 p-0", className)}
      {...props}
    />
  );
}
export function PaginationItem(props: React.ComponentProps<"li">) {
  return <li {...props} />;
}
export function PaginationLink({
  isActive = false,
  className,
  ...props
}: React.ComponentProps<"a"> & { isActive?: boolean }) {
  return (
    <a
      aria-current={isActive ? "page" : undefined}
      className={cn(
        "inline-flex min-h-10 min-w-10 items-center justify-center rounded-lg border border-transparent px-3 text-sm hover:bg-muted",
        isActive && "border-border bg-muted font-medium",
        className,
      )}
      {...props}
    />
  );
}
export function PaginationPrevious({
  children = "Previous",
  ...props
}: React.ComponentProps<typeof PaginationLink>) {
  return (
    <PaginationLink aria-label="Previous page" {...props}>
      {children}
    </PaginationLink>
  );
}
export function PaginationNext({
  children = "Next",
  ...props
}: React.ComponentProps<typeof PaginationLink>) {
  return (
    <PaginationLink aria-label="Next page" {...props}>
      {children}
    </PaginationLink>
  );
}
export function PaginationEllipsis({
  className,
  ...props
}: React.ComponentProps<"span">) {
  return (
    <span
      aria-hidden
      className={cn(
        "inline-flex size-10 items-center justify-center text-muted-foreground",
        className,
      )}
      {...props}
    >
      …
    </span>
  );
}

registry/ui/utils.ts

Scroll horizontally for long lines
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...values: ClassValue[]) {
  return twMerge(clsx(values));
}

registry/ui/button.tsx

Scroll horizontally for long lines
"use client";
import * as React from "react";
import { Slot } from "radix-ui";
import { LoaderCircle } from "lucide-react";
import { cn } from "./utils";
export type ButtonProps = React.ComponentProps<"button"> & {
  variant?: "primary" | "secondary" | "outline" | "ghost" | "danger";
  size?: "sm" | "md" | "lg";
  loading?: boolean;
  asChild?: boolean;
};
export function Button({
  variant = "primary",
  size = "md",
  loading,
  asChild,
  className,
  children,
  disabled,
  ...props
}: ButtonProps) {
  const Comp = asChild ? Slot.Root : "button";
  return (
    <Comp
      type={asChild ? undefined : "button"}
      disabled={asChild ? undefined : disabled || loading}
      aria-disabled={disabled || loading || undefined}
      aria-busy={loading || undefined}
      className={cn(
        "relative inline-flex shrink-0 items-center justify-center gap-2 whitespace-nowrap rounded-lg border border-transparent text-sm font-medium leading-none transition-[background-color,border-color,box-shadow,transform] duration-150 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary active:scale-[.98] disabled:pointer-events-none disabled:opacity-45 aria-disabled:pointer-events-none [&_svg]:shrink-0",
        {
          "bg-primary text-primary-foreground shadow-[inset_0_1px_0_#ffffff26,0_1px_2px_#00000012] hover:bg-primary/90":
            variant === "primary",
          "border-border/60 bg-muted text-foreground hover:bg-muted/70":
            variant === "secondary",
          "border-border bg-background text-foreground shadow-sm hover:bg-muted/60":
            variant === "outline",
          "text-muted-foreground hover:bg-muted hover:text-foreground":
            variant === "ghost",
          "bg-danger text-danger-foreground hover:bg-danger/90":
            variant === "danger",
        },
        {
          "h-8 px-3 text-xs": size === "sm",
          "h-10 px-4": size === "md",
          "h-12 px-6": size === "lg",
        },
        className,
      )}
      {...props}
    >
      {asChild ? (
        children
      ) : (
        <>
          <span
            className={cn(
              "inline-flex min-w-0 flex-1 items-center justify-center gap-2",
              loading && "invisible",
            )}
          >
            {children}
          </span>
          {loading && (
            <LoaderCircle
              aria-hidden="true"
              className="absolute size-4 animate-spin motion-reduce:animate-none"
            />
          )}
        </>
      )}
    </Comp>
  );
}

registry/ui/use-controllable.ts

Scroll horizontally for long lines
"use client";
import { useRef, useState, type SetStateAction } from "react";
/** Controlled or instance-local state. Functional updates also work before a rerender. */
export function useControllable<T>(
  value: T | undefined,
  initial: T,
  onChange?: (value: T) => void,
) {
  const [local, setLocal] = useState(initial);
  const current = useRef(value === undefined ? local : value);
  current.current = value === undefined ? local : value;
  return [
    current.current,
    (action: SetStateAction<T>) => {
      const next =
        typeof action === "function"
          ? (action as (previous: T) => T)(current.current)
          : action;
      current.current = next;
      if (value === undefined) setLocal(next);
      onChange?.(next);
    },
  ] as const;
}

Dependencies

clsx@2.1.1 · tailwind-merge@3.5.0 · radix-ui@1.6.7 · lucide-react@0.577.0

Accessibility & behaviour

Provide meaningful labels and preserve keyboard focus styles. Check contrast when customising theme colours.

Read the accessibility and performance guide →