Pagination

Atom
Page-of-N navigation for tables and lists.
src/atoms/pagination
View in Navigation

Playground

Every control sets a real prop of PaginationProps. The JSX below updates as you go.
Props
page
number
4
total
number
12
Variant
pick one
Size
pick one
disabled
boolean
JSX · PaginationProps
<Pagination page={4} total={12} />

Variants

4 examples from src/atoms/pagination/pagination.md, each rendered live from its own JSX.
Showing 11-20 of 118
With item range
<Pagination compact defaultPage={2} total={12} itemCount={118} />
Rows per page
Page 2 of 12
With size
<Pagination defaultPage={2} total={12} withSize defaultPageSize={10} pageSizes={[10, 25, 50]} />
Sizes
<Column relaxed>
<Pagination small defaultPage={2} total={12} />
<Pagination defaultPage={2} total={12} />
<Pagination large defaultPage={2} total={12} />
</Column>
First and last page
<Column relaxed>
<Pagination defaultPage={1} total={3} />
<Pagination defaultPage={3} total={3} />
</Column>

Sizes

small
default
large

States

Hover, focus and press are pinned so they can be compared side by side; the rest are real props.
default
hover
focus
disabled

Anatomy

1
Previous
2
Page
3
Current page
4
Ellipsis
5
Next
Dimmed parts appear only in some states or variants.

Props

16 props on PaginationProps, grouped as they are declared in source. Required props are marked *.
Prop
Type
Default
Description
Props
5 props
page
number
–
Current page, 1-based (CONTROLLED). Clamped into the 1..total range before rendering. Omit for uncontrolled use.
defaultPage
number
–
Initial page for uncontrolled use (a bare pagination navigates on press).
total
number
–
Total number of pages.
onChange
(page: number) => void
–
Fired with the next 1-based page when a control or number is pressed.
itemCount
number
–
Total number of items across all pages. When set, the compact and with-size indicator reads "Showing X-Y of N" (the item range on the current page) instead of "Page X of N", computed from the current page and the page size.
Variant
pick one
2 props
compact
boolean
false
Collapse to Prev/Next plus a "Page X of N" label, no number buttons.
withSize
boolean
false
Prepend a "Rows per page" size selector to the compact Prev/Next + "Page X of N" layout. Takes precedence over compact.
Content for the `withSize` selector
4 props
pageSize
number
–
Currently selected rows-per-page value shown in the selector (CONTROLLED). Omit for uncontrolled use.
defaultPageSize
number
–
Initial rows-per-page value for uncontrolled use (the selector cycles on press).
pageSizes
number[]
–
Selectable rows-per-page values; pressing the selector advances through them.
onPageSizeChange
(size: number) => void
–
Fired with the next rows-per-page value when the selector is pressed.
Size
pick one
5 props
small
boolean
false
large
boolean
false
disabled
boolean
false
testID
string
–
E2E hook forwarded to the root element.
style
LayoutStyle
–
Composition within a parent only, never a restyle hook and never a width: the parent layout container provides the bounds.

Accessibility and keyboard

Keyboard
Tab
Moves between links
Enter
Follows the link
Semantics
Roles
button
States
disabled
selected
ARIA on web
aria-current
aria-disabled
aria-hidden
Below the platform minimum, the touch area grows to 44 pt on iOS and 48 dp on Android without moving the layout.

Platform skins

The playground's props on each platform: same tree, native shapes, type and touch sizes.
Web
control 10 · field 10 · card 16 · Instrument Sans
iOS
capsule controls · field 8 · card 12 · SF Pro · 44 pt
Android
Material 3 stadium · field 4 · card 12 · Roboto · 48 dp

Usage

<Pagination defaultPage={2} total={12} />
Neither iOS nor Android has a numbered pagination control, so every platform shows the same pager: rounded hairline cells at 28, 34 or 40 (small, default, large), the page numbers in 13px mono numerals, and the current page in the accent fill with a soft glow beneath it. Previous and Next carry a chevron and a "Prev" / "Next" label beside the numbers (the chevron alone at the small size and in the compact row), the truncation gap is a quiet text ellipsis (…), and the rows-per-page trigger sits on the field edge. A resting page or arrow takes the hover wash at once; a disabled pager dims as one, and in an enabled pager the arrow at either end dims on its own.
In glass mode the current page is a brand-tinted control-layer puck behind its number; the other pages and the hairline arrows paint no surface, so they stay bare. Beyond seven pages a page change also shifts the window (an ellipsis moves, a number appears or drops out). Solid mode keeps the accent fill.

Tokens

Read from the playground render. Values follow the scheme and the ion hue.
--fd
--fm
--ft
--ion
--ion-fg
--ion-glow
--ln
--tx2
--tx3

Related components