Pagination

Install

pnpm dlx shadcn@latest add @vegastack/pagination

Usage

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

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

Anatomy

Pagination is a compound component built from a presentational <nav> wrapping an unordered list of page controls. Compose the parts inside the root — every part exposes a data-slot:

<Pagination aria-label="Search results pagination">
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious href="?page=1" />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="?page=1">1</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="?page=2" isActive>
        2 {/* current page */}
      </PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationEllipsis /> {/* collapse a long range */}
    </PaginationItem>
    <PaginationItem>
      <PaginationNext href="?page=2" />
    </PaginationItem>
  </PaginationContent>
</Pagination>

• Pagination — the navigation landmark (data-slot="pagination"). Renders a plain <nav> — <nav> is the landmark, so no explicit role — labelled "Pagination" unless you pass your own aria-label.
• PaginationContent — the list of controls (<ul>, data-slot="pagination-content"). Flex-aligned with a consistent gap.
• PaginationItem — a single list slot (<li>, data-slot="pagination-item").
• PaginationLink — a navigable page link (<a>, data-slot="pagination-link"). Styled like a ghost/outline button; set isActive on the current page and choose a size. Supports the Base UI render prop for client-side routing.
• PaginationPrevious — a labelled "previous page" control (<a>) with a leading chevron.
• PaginationNext — a labelled "next page" control (<a>) with a trailing chevron.
• PaginationEllipsis — a decorative collapsed-pages indicator (data-slot="pagination-ellipsis", aria-hidden) for long ranges.

Examples

Routing links

Use the render prop on PaginationLink (and PaginationPrevious/PaginationNext) to compose with your router's link component while keeping pagination styling and semantics:

import Link from "next/link";

<PaginationLink render={<Link href="?page=2" />} isActive>
  2
</PaginationLink>;

Sizes

PaginationLink takes a size prop — sm (28px), md (32px), lg (40px), and icon (a 32px square, the square default for numbered pages) — on the same 28/32/40 control scale as buttons and inputs. The grid below renders all four: icon is the squared-off default, sm/md/lg widen the hit target with horizontal padding.

Edge states

When a previous/next control is unavailable, omit href and set aria-disabled="true" — the link then enforces the disabled state itself (removed from the tab order, clicks and Enter blocked). A disabled link can never navigate.

On the first page, disable PaginationPrevious:

On the last page, mirror the pattern on PaginationNext:

Positional pager

PaginationPager is the compact record-pager: previous/next steppers + a "n of N [context]" status label (bounds-disabled at the ends, tabular numerals). Use it for stepping through items of a known list; keep Pagination for numbered page navigation.

Playground

Try every page-link size on a live pagination bar, then copy the generated JSX.

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

API Reference

PaginationLink

PaginationPrevious / PaginationNext

PaginationPrevious and PaginationNext accept exactly the same props as PaginationLink (isActive, size, render, plus native <a> props) — they pre-compose the directional chevron and label.

Pagination, PaginationContent, PaginationItem, and PaginationEllipsis add no props of their own — each accepts everything its underlying native element accepts (<nav>, <ul>, <li>, <span>), plus className and ref.

Accessibility

• The root is a navigation landmark: a plain <nav aria-label="Pagination">. <nav> already carries the landmark role, so the component does not restate it.
• Name every pager on a page that has more than one. Two landmarks with the same accessible name are an axe landmark-unique failure and give screen-reader users no way to tell them apart. Pass aria-label="Search results pagination", aria-label="Invoices pagination", and so on — the default "Pagination" is correct only when the page has exactly one.
• The active page uses aria-current="page", so it is announced as the current location in the set.
• Previous/Next controls carry an explicit aria-label ("Go to previous page" / "Go to next page") so the icon-only direction is still meaningful to screen readers.
• PaginationEllipsis is decorative (aria-hidden="true"). Use real page links or a separate labelled menu trigger when skipped pages need to be reachable.
• Disabled Previous/Next controls omit href and set aria-disabled — the component then removes them from the tab order and blocks activation itself (an aria-disabled anchor is otherwise not inert).
• Links use the native <a> and keep a visible :focus-visible ring — never outline: none.

Do / Don't