Skip to main content

Pagination

Steps through content split across numbered pages.

import { Pagination } from "@/fragments/ui";Source

Preview

<Pagination totalPages={10} defaultPage={1}>
  <Pagination.Previous />
  <Pagination.Items />
  <Pagination.Next />
</Pagination>

Installation

npx @usefragments/cli add pagination

Writes src/fragments/ui/components/Pagination plus what it imports, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add. No account, no key.

Your own registry: publish from Fragments Cloud and add --registry org/name. Connect a workspace.

Anatomy

Pagination is a compound: import the root and reach its parts through dot notation.

  • Pagination.Previous
  • Pagination.Next
  • Pagination.Items
  • Pagination.Item
  • Pagination.Ellipsis

Neighbours around the current page, ends always reachable.

<Pagination totalPages={10} defaultPage={1}>
  <Pagination.Previous />
  <Pagination.Items />
  <Pagination.Next />
</Pagination>

Examples

With Edge Pages

Two pages pinned at each end.

<Pagination totalPages={20} defaultPage={10} edgeCount={2} siblingCount={1}>
  <Pagination.Previous />
  <Pagination.Items />
  <Pagination.Next />
</Pagination>

Compact

Drops the neighbours when space is tight.

<Pagination totalPages={20} defaultPage={10} siblingCount={0}>
  <Pagination.Previous />
  <Pagination.Items />
  <Pagination.Next />
</Pagination>

Controlled

You hold the page number in state.

<Pagination totalPages={5} page={3}>
  <Pagination.Previous />
  <Pagination.Items />
  <Pagination.Next />
</Pagination>

API

Component props
Prop
Type
Default
Description
childrenRequirednodeNot set—
totalPagesRequirednumberNot setTotal number of pages
pagenumberNot setControlled current page (1-indexed)
defaultPagenumber1Default page (uncontrolled)
onPageChangefunctionNot setCalled when page changes
edgeCountnumber1Number of pages shown at edges
siblingCountnumber1Number of pages shown around current
sizeenumsmmdlgNot setVisible action size. Resolves through ComponentDefaults when omitted.

Accessibility

  • Uses nav element with aria-label="Pagination"
  • aria-current="page" marks the active page
  • Previous/Next buttons have descriptive aria-labels
  • Disabled buttons at boundaries prevent invalid navigation

Guidance

Use when

  • Data sets served a page at a time
  • Tables and lists with a known total
  • Search results past the first screen

Avoid when

  • Everything already fits on one page
  • Content that loads as the user scrolls
  • Switching between panels (use Tabs)
  • Steps in an order (use Stepper)

Related

  • TablesiblingCommonly paired for table pagination
  • ListboxalternativeUse Listbox for small sets of options

Next steps