Pagination

import { useState } from "react";
import { Paginator } from "@/components/ui/pagination";

export default function PaginationDemo() {
  const [page, setPage] = useState(5);
  return <Paginator page={page} pageCount={20} onPageChange={setPage} />;
}

Installation

$ pnpm dlx shadcn@latest add @desyne/pagination

The CLI installs dependencies and any other components this one uses.

Usage

tsx

import { Paginator } from "@/components/ui/pagination";

tsx

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

<Paginator page={page} pageCount={20} onPageChange={setPage} />;

For link-based pagination, where each page has its own URL, compose the parts:

tsx

import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@/components/ui/pagination";

tsx

<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious href="?page=1" />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="?page=2" isActive>2</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationNext href="?page=3" />
    </PaginationItem>
  </PaginationContent>
</Pagination>

When to use

Paginator — client-side state: tables, lists and search results where the page lives in React state and URLs don't need to change.
Link-based parts — server-rendered or routed lists where each page should be linkable, bookmarkable and crawlable (?page=3).
Simple mode — narrow spaces like card footers and mobile layouts, or very large page counts where numbers don't help.
Consider infinite scrolling or a "Load more" Button for feeds, where users browse rather than look for a specific page.

Anatomy

tsx

<Pagination>                 {/* <nav aria-label="pagination"> */}
  <PaginationContent>        {/* <ul> */}
    <PaginationItem>         {/* <li> */}
      <PaginationPrevious />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink />     {/* page number */}
    </PaginationItem>
    <PaginationItem>
      <PaginationEllipsis /> {/* skipped pages */}
    </PaginationItem>
    <PaginationItem>
      <PaginationNext />
    </PaginationItem>
  </PaginationContent>
</Pagination>

<Paginator />                {/* all of the above, with buttons, in one component */}

Part	Renders	Notes
`Pagination`	`<nav aria-label="pagination">`	Landmark. Centered, full width by default.
`PaginationContent`	`<ul>`	Row of items with `gap-1`.
`PaginationItem`	`<li>`	Wraps one link, button or ellipsis.
`PaginationLink`	React Aria `Link`	A page link styled with `buttonVariants`: `ghost` normally, `outline` with a primary border when `isActive` (which also sets `aria-current="page"`).
`PaginationPrevious` / `PaginationNext`	`PaginationLink`	Chevron plus "Previous" / "Next" text. The text is hidden below the `sm` breakpoint.
`PaginationEllipsis`	`<span aria-hidden>`	"…" icon for skipped pages.
`Paginator`	`Pagination` with buttons	Previous and next icon buttons, page-number buttons from `getPageRange()`, or "Page x of y" in simple mode.

Examples

Sizes

md (32px, default) and sm (28px) for tables and dense toolbars.

import { useState } from "react";
import { Paginator } from "@/components/ui/pagination";

export default function PaginationSizes() {
  const [page, setPage] = useState(4);
  return (
    <div className="flex flex-col items-center gap-4">
      <Paginator size="sm" page={page} pageCount={12} onPageChange={setPage} />
      <Paginator size="md" page={page} pageCount={12} onPageChange={setPage} />
    </div>
  );
}

Simple

simple replaces the page numbers with "Page x of y" between the arrows. It takes a fixed amount of space regardless of the page count.

import { useState } from "react";
import { Paginator } from "@/components/ui/pagination";

export default function PaginationSimple() {
  const [page, setPage] = useState(3);
  return <Paginator simple page={page} pageCount={42} onPageChange={setPage} />;
}

Siblings

siblings sets how many pages are shown on each side of the current page (default 1). The first and last pages are always shown, and a gap becomes an ellipsis.

siblings=0

siblings=1

siblings=2

import { useState } from "react";
import { Paginator } from "@/components/ui/pagination";

export default function PaginationSiblings() {
  const [page, setPage] = useState(10);
  return (
    <div className="flex flex-col items-center gap-4">
      {[0, 1, 2].map((siblings) => (
        <div key={siblings} className="flex flex-col items-center gap-1.5">
          <span className="text-muted-foreground text-xs">
            siblings={siblings}
          </span>
          <Paginator
            size="sm"
            siblings={siblings}
            page={page}
            pageCount={20}
            onPageChange={setPage}
          />
        </div>
      ))}
    </div>
  );
}

Few pages

When every page fits (pageCount up to siblings * 2 + 5, so 7 by default), all numbers are shown with no ellipsis. Previous is disabled on the first page and Next on the last.

import { useState } from "react";
import { Paginator } from "@/components/ui/pagination";

export default function PaginationFewPages() {
  const [page, setPage] = useState(1);
  return <Paginator page={page} pageCount={5} onPageChange={setPage} />;
}

Link-based

Compose PaginationLink, PaginationPrevious, PaginationNext and PaginationEllipsis when each page is a URL. Mark the current page with isActive.

import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@/components/ui/pagination";

export default function PaginationLinks() {
  return (
    <Pagination>
      <PaginationContent>
        <PaginationItem>
          <PaginationPrevious href="#" />
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#">1</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#" isActive>
            2
          </PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#">3</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationEllipsis />
        </PaginationItem>
        <PaginationItem>
          <PaginationLink href="#">10</PaginationLink>
        </PaginationItem>
        <PaginationItem>
          <PaginationNext href="#" />
        </PaginationItem>
      </PaginationContent>
    </Pagination>
  );
}

Link sizes

Link parts accept size="sm" or size="md" ("default" and "icon" are accepted as aliases for md).

import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@/components/ui/pagination";

export default function PaginationLinksSizes() {
  return (
    <div className="flex flex-col items-center gap-4">
      {(["sm", "md"] as const).map((size) => (
        <Pagination key={size}>
          <PaginationContent>
            <PaginationItem>
              <PaginationPrevious href="#" size={size} />
            </PaginationItem>
            {[1, 2, 3].map((p) => (
              <PaginationItem key={p}>
                <PaginationLink href="#" size={size} isActive={p === 1}>
                  {p}
                </PaginationLink>
              </PaginationItem>
            ))}
            <PaginationItem>
              <PaginationNext href="#" size={size} />
            </PaginationItem>
          </PaginationContent>
        </Pagination>
      ))}
    </div>
  );
}

With a router and getPageRange

Build the page list with getPageRange(page, pageCount, siblings?), which returns numbers and "ellipsis" markers, and disable Previous and Next at the ends with isDisabled. Wrap the app in React Aria's RouterProvider so the links use client-side navigation. The preview uses a local stand-in for the router.

import { useState } from "react";
import { RouterProvider } from "react-aria-components";
import {
  getPageRange,
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@/components/ui/pagination";

const pageCount = 24;

export default function PaginationLinksRouter() {
  // Stand-in for your router. In Next.js read `useSearchParams()` and pass
  // `useRouter().push` to RouterProvider in your app's providers.
  const [page, setPage] = useState(1);
  const href = (p: number) => `?page=${p}`;

  return (
    <RouterProvider
      navigate={(to) => setPage(Number(new URLSearchParams(to).get("page")))}
    >
      <Pagination>
        <PaginationContent>
          <PaginationItem>
            <PaginationPrevious href={href(page - 1)} isDisabled={page <= 1} />
          </PaginationItem>
          {getPageRange(page, pageCount).map((p, i) =>
            p === "ellipsis" ? (
              // biome-ignore lint/suspicious/noArrayIndexKey: at most two ellipses
              <PaginationItem key={`e${i}`}>
                <PaginationEllipsis />
              </PaginationItem>
            ) : (
              <PaginationItem key={p}>
                <PaginationLink
                  href={href(p)}
                  isActive={p === page}
                  aria-label={`Page ${p}`}
                >
                  {p}
                </PaginationLink>
              </PaginationItem>
            ),
          )}
          <PaginationItem>
            <PaginationNext
              href={href(page + 1)}
              isDisabled={page >= pageCount}
            />
          </PaginationItem>
        </PaginationContent>
      </Pagination>
    </RouterProvider>
  );
}

With the Next.js App Router, read the page from the URL:

app/invoices/page.tsxtsx

import { InvoicePagination } from "./invoice-pagination";

export default async function Page({ searchParams }: { searchParams: Promise<{ page?: string }> }) {
  const page = Number((await searchParams).page ?? 1);
  // …fetch the rows for `page`
  return <InvoicePagination page={page} pageCount={24} />;
}

InvoicePagination is a client component that renders the parts as in the preview, with an href of ?page=N for each page. Your app's RouterProvider passes router.push as navigate.

getPageRange(5, 10); // [1, "ellipsis", 4, 5, 6, "ellipsis", 10]
getPageRange(2, 10); // [1, 2, 3, "ellipsis", 10]
getPageRange(2, 6); // [1, 2, 3, 4, 5, 6]

Recipes

A rows-per-page Select, a range summary and a small paginator under a Table. Changing the page size resets to page 1. Pass className="mx-0 w-auto" to stop the paginator from centering itself.

Invoice	Customer	Status	Amount
INV-1001	Acme Corp	Paid	$480.00
INV-1002	Globex	Pending	$5,105.00
INV-1003	Initech	Overdue	$4,730.00
INV-1004	Umbrella	Paid	$4,355.00
INV-1005	Hooli	Pending	$3,980.00

Rows per page

1–5 of 57

import { useState } from "react";
import { Badge } from "@/components/ui/badge";
import { Paginator } from "@/components/ui/pagination";
import { Select, SelectItem } from "@/components/ui/select";
import {
  Cell,
  Column,
  Row,
  Table,
  TableBody,
  TableHeader,
} from "@/components/ui/table";

const customers = [
  "Acme Corp",
  "Globex",
  "Initech",
  "Umbrella",
  "Hooli",
  "Stark Industries",
  "Wayne Enterprises",
];
const statuses = ["Paid", "Pending", "Overdue"] as const;
const tone = {
  Paid: "success",
  Pending: "warning",
  Overdue: "danger",
} as const;

const invoices = Array.from({ length: 57 }, (_, i) => ({
  id: `INV-${1001 + i}`,
  customer: customers[i % customers.length],
  status: statuses[(i * 7) % 3],
  amount: `$${(((i * 37) % 40) * 125 + 480).toLocaleString()}.00`,
}));

export default function PaginationRecipeTable() {
  const [page, setPage] = useState(1);
  const [pageSize, setPageSize] = useState(5);
  const pageCount = Math.ceil(invoices.length / pageSize);
  const start = (page - 1) * pageSize;
  const rows = invoices.slice(start, start + pageSize);

  return (
    <div className="grid w-full max-w-2xl gap-3">
      <Table aria-label="Invoices" className="min-w-[480px]">
        <TableHeader>
          <Column isRowHeader>Invoice</Column>
          <Column>Customer</Column>
          <Column>Status</Column>
          <Column className="text-right">Amount</Column>
        </TableHeader>
        <TableBody items={rows}>
          {(invoice) => (
            <Row>
              <Cell className="font-medium">{invoice.id}</Cell>
              <Cell>{invoice.customer}</Cell>
              <Cell>
                <Badge variant="dot" color={tone[invoice.status]}>
                  {invoice.status}
                </Badge>
              </Cell>
              <Cell className="text-right tabular-nums">{invoice.amount}</Cell>
            </Row>
          )}
        </TableBody>
      </Table>
      <div className="flex flex-wrap items-center justify-between gap-3">
        <div className="flex items-center gap-2 text-muted-foreground text-sm">
          <span id="rows-per-page">Rows per page</span>
          <Select
            aria-labelledby="rows-per-page"
            size="sm"
            className="w-20"
            selectedKey={String(pageSize)}
            onSelectionChange={(key) => {
              setPageSize(Number(key));
              setPage(1);
            }}
          >
            <SelectItem id="5">5</SelectItem>
            <SelectItem id="10">10</SelectItem>
            <SelectItem id="20">20</SelectItem>
          </Select>
        </div>
        <span className="text-muted-foreground text-sm tabular-nums">
          {start + 1}–{Math.min(start + pageSize, invoices.length)} of{" "}
          {invoices.length}
        </span>
        <Paginator
          size="sm"
          page={page}
          pageCount={pageCount}
          onPageChange={setPage}
          className="mx-0 w-auto"
        />
      </div>
    </div>
  );
}

Card footer

A compact simple paginator aligned to the end of a Card footer with className="justify-end".

Recent activity

Everything that happened in your workspace.

MC
Maya Chen deployed acme-web to production2m ago
OF
Omar Farouk merged #482 Add checkout retries18m ago
LP
Lena Park invited 3 people to Growth1h ago

import { useState } from "react";
import { Avatar } from "@/components/ui/avatar";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
import { Paginator } from "@/components/ui/pagination";

const events = [
  { who: "Maya Chen", what: "deployed acme-web to production", when: "2m ago" },
  {
    who: "Omar Farouk",
    what: "merged #482 Add checkout retries",
    when: "18m ago",
  },
  { who: "Lena Park", what: "invited 3 people to Growth", when: "1h ago" },
  { who: "Maya Chen", what: "rotated the Stripe API key", when: "3h ago" },
  { who: "Diego Ruiz", what: "opened #489 Flaky login test", when: "5h ago" },
  {
    who: "Lena Park",
    what: "changed the billing plan to Pro",
    when: "Yesterday",
  },
  {
    who: "Omar Farouk",
    what: "deleted the staging-old branch",
    when: "Yesterday",
  },
  { who: "Diego Ruiz", what: "created the Q4 roadmap doc", when: "2d ago" },
  { who: "Maya Chen", what: "enabled SSO for acme.dev", when: "3d ago" },
];

const pageSize = 3;

export default function PaginationRecipeActivity() {
  const [page, setPage] = useState(1);
  const items = events.slice((page - 1) * pageSize, page * pageSize);

  return (
    <Card className="w-full max-w-md">
      <CardHeader>
        <CardTitle>Recent activity</CardTitle>
        <CardDescription>
          Everything that happened in your workspace.
        </CardDescription>
      </CardHeader>
      <CardContent>
        <ul className="grid gap-4">
          {items.map((e) => (
            <li
              key={`${e.who}-${e.what}`}
              className="flex items-start gap-3 text-sm"
            >
              <Avatar
                size="sm"
                colorful
                fallback={e.who
                  .split(" ")
                  .map((n) => n[0])
                  .join("")}
                alt={e.who}
              />
              <div className="grid gap-0.5">
                <span>
                  <span className="font-medium">{e.who}</span>{" "}
                  <span className="text-muted-foreground">{e.what}</span>
                </span>
                <span className="text-muted-foreground text-xs">{e.when}</span>
              </div>
            </li>
          ))}
        </ul>
      </CardContent>
      <CardFooter className="border-t">
        <Paginator
          simple
          size="sm"
          page={page}
          pageCount={Math.ceil(events.length / pageSize)}
          onPageChange={setPage}
          className="justify-end"
        />
      </CardFooter>
    </Card>
  );
}

Accessibility

Rendered in a <nav aria-label="pagination"> landmark. Pass your own aria-label (for example "Search results pages") when a page has more than one.
The current page has aria-current="page".
Paginator labels its buttons "Previous page", "Next page" and "Page 3"; the link parts label Previous and Next "Go to previous page" and "Go to next page". Override any of them with aria-label.
Previous and Next are disabled (and removed from the tab order) at the ends.
Ellipses are aria-hidden.
After changing pages in client-side lists, consider moving focus to the top of the results or announcing the change, so screen-reader users know the content updated.

Keyboard

Key	Action
`Tab` / `Shift`+`Tab`	Moves between the controls
`Enter`	Activates the focused page, Previous or Next
`Space`	Activates a `Paginator` button (links respond to `Enter` only)

Styling

Data attributes

On PaginationLink, PaginationPrevious, PaginationNext and the Paginator buttons:

Attribute	Present when
`data-hovered` / `data-pressed`	Hovered / being pressed
`data-focus-visible`	Focused with the keyboard
`data-disabled`	Disabled
`data-active`	Link parts with `isActive`
`data-current`	Link parts with `isActive` (from `aria-current`)

Slots

`data-slot`	Element
`pagination`	`<nav>` root
`pagination-content`	`<ul>`
`pagination-item`	Each `<li>`
`pagination-link`	Each link part
`pagination-ellipsis`	Ellipsis

Customizing

Items use buttonVariants, so they follow button tones and radii. Page numbers are tabular-nums so widths don't shift.
className on Pagination or Paginator styles the <nav>. It's centered with mx-auto flex w-full justify-center; use justify-start, justify-end or mx-0 w-auto to align it.
className on PaginationLink must be a string.

API Reference

Paginator

Prop

Type

Also accepts every prop of <nav> except onChange.

PaginationLink

Prop

Type

Also accepts every prop of React Aria's Link except a function className.

PaginationPrevious / PaginationNext

Accept the same props as PaginationLink. Their content is fixed (chevron and label); aria-label defaults to "Go to previous page" / "Go to next page".

Pagination / PaginationContent / PaginationItem / PaginationEllipsis

Accept every prop of <nav> / <ul> / <li> / <span>.

getPageRange

Prop

Type

Returns (number | "ellipsis")[]: always the first and last page, the current page with its siblings, and "ellipsis" for each gap. When pageCount is at most siblings * 2 + 5, returns every page.

Table — the most common place for pagination.
Select — rows-per-page pickers.
Link — the link used by the link-based parts.
Button — buttonVariants styles every item.