7onicDESIGN SYSTEM

Pagination

Pagination splits large amounts of data into pages, allowing users to navigate to any page. Configurable sibling and boundary ranges automatically calculate page ranges including ellipsis (…).

3
Variants
5
Sizes
4
Navigation
Pure
React

Playground

Preview
DdefaultPage 1/20
Variant
Color
Size
Radius
Pages
Options
const [page, setPage] = useState(1)

<Pagination total={20} value={page} onChange={setPage} />

Variants

Default
Solid fill on active page — the most common style
Standard UI
Outline
Bordered buttons — active page uses solid fill
Forms & lists
Ghost
Subtle highlight on active page — minimal visual weight
Secondary UI

Sizes

xs
Height28px
Font12px
Icon14px
sm
Height32px
Font13px
Icon14px
default
Height36px
Font14px
Icon16px
lg
Height40px
Font14px
Icon16px
xl
Height48px
Font16px
Icon16px

Features

Edge Navigation (withEdges)

First/last jump buttons for quick navigation across many pages

<Pagination total={20} defaultValue={10} withEdges />

Loop Navigation (loop)

Wraps from last page to first, and first page to last

<Pagination total={5} defaultValue={5} loop />

Disabled State

Disables all interaction — useful during data loading

<Pagination total={10} defaultValue={3} disabled />

Custom Icons

Replace built-in icons with any ReactNode via the icon prop

<Pagination total={10} defaultValue={5}>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious icon={
        <svg className="icon-sm" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
          <path strokeLinecap="round" strokeLinejoin="round" d="M10 19l-7-7m0 0l7-7m-7 7h18" />
        </svg>
      } />
    </PaginationItem>
    <PaginationItems />
    <PaginationItem>
      <PaginationNext icon={
        <svg className="icon-sm" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
          <path strokeLinecap="round" strokeLinejoin="round" d="M14 5l7 7m0 0l-7 7m7-7H3" />
        </svg>
      } />
    </PaginationItem>
  </PaginationContent>
</Pagination>

API

Component Structure

Pagination— Pure React
.Content.Item.LinkProps.PreviousProps.NextProps.FirstProps.LastProps.Ellipsis.Items

Props

Pagination

total1
number

Total number of pages

valueundefined
number

Current page (controlled mode)

defaultValue1
number

Initial page (uncontrolled mode)

onChangeundefined
(page: number) => void

Callback on page change

siblings1
number

Pages shown on each side of the current page

boundaries1
number

Pages always shown at the start and end

size"default"
"xs" | "sm" | "default" | "lg" | "xl"

Component size (28/32/36/40/48px)

variant"default"
"default" | "outline" | "ghost"

Visual variant

color"default"
"default" | "primary"

Active page color

radius"md"
"sm" | "base" | "md" | "lg" | "xl" | "full"

Border radius

disabledfalse
boolean

Disables all interaction

withControlstrue
boolean

Show previous/next buttons

withEdgesfalse
boolean

Show first/last jump buttons

loopfalse
boolean

Loop from last to first page

PaginationLink

pageundefined
number

Target page number

isActiveauto
boolean

Active state (auto-detected from context if omitted)

PaginationPrevious / PaginationNext / PaginationFirst / PaginationLast

iconBuilt-in SVG icon
ReactNode

Custom icon

Anatomy

1
2
3
Prev
4
1
7
…
4
5
5
6
…
10
6
Next
Height36px
Min widthmin-w-9
Gapgap-1
Iconicon-sm
1
Root
nav container
2
Content
Flex list
3
Prev / Next
Prev/next buttons
4
Page Item
Page number
5
Active Page
Active page
6
Ellipsis
Ellipsis

Best Practices

✓

Do

  • ✓Use pagination when the total data set is large
  • ✓Clearly indicate the current page position
  • ✓Configure siblings and boundaries for an appropriate page range
  • ✓Use withEdges for large page counts to provide first/last jump buttons
✕

Don't

  • ✗Don't paginate small data sets — show all items instead
  • ✗Don't skip resetting scroll position on page change
  • ✗Don't display all page numbers at once — use siblings/boundaries
  • ✗Avoid combining with infinite scroll

Accessibility

Keyboard

TabNavigate between page buttons
Enter / SpaceSelect page

ARIA / WCAG

  • role="navigation" on the nav element
  • aria-label="pagination" — identifies the navigation region
  • aria-current="page" on the current page
  • aria-label="Go to page N" on each button
  • default 36px, lg 40px+ (WCAG 2.5.8 compliant)
  • aria-hidden="true" on Ellipsis