Pagination

Pagination is a set of composable primitives for building a paged navigation bar. It renders a labeled nav landmark and gives you the page links, previous/next controls, and an ellipsis for collapsed ranges. You assemble the pieces yourself, so the page numbers, the active page, and the href wiring are entirely under your control.

Live demo

The interactive story below runs from the deployed Storybook.

Usage

Source: pagination.tsx

import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@beacon/design-system";

<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>
      <PaginationNext href="#" />
    </PaginationItem>
  </PaginationContent>
</Pagination>

Parts

Part	Role
Pagination	Root nav landmark with aria-label="pagination". Centers the control.
PaginationContent	The ul that lays the items out in a row.
PaginationItem	A single li wrapper around a link, ellipsis, or control.
PaginationLink	A page-number a. Set isActive to mark the current page (aria-current="page").
PaginationPrevious	A PaginationLink preset with a left chevron and “Previous” label.
PaginationNext	A PaginationLink preset with a right chevron and “Next” label.
PaginationEllipsis	A non-interactive gap marker for collapsed page ranges.

PaginationLink props

Prop	Type	Default	Description
isActive	boolean	false	Marks the current page; renders the outline button style and sets aria-current="page".
size	"default" | "sm" | "lg" | "icon"	"icon"	Forwarded to the underlying button style.
href	string	n/a	Standard anchor target. All other native a attributes pass through.

When to use

• Paged data tables where the full result set is split across numbered pages.
• Long lists of records (liens, notices, work orders) that load one page at a time.
• Anywhere the user needs to jump to a specific page or step forward and back.

Do not use Pagination for switching between sibling views or sections; reach for Tab bars instead.