Pagination | Sodium design system

Mode

When to use it

6 rules

Must: Give every page an href with getHref or hrefPattern, even when onPageChange handles the click. Because a real link opens in a new tab and can be shared, and the page survives a reload.
Never: Mark the current page with the yellow slab or an edged box. Because the current page is where you are, so it takes the selection wash; the slab is for the one action.
Must: Leave out pages for a cursor API and pass hasNext. Because a made-up total promises pages that are not there.
Should: Pair it with PaginationInfo, saying the range and the total. Because the numbers say where you are; the range says what you are looking at.
Should: Use size="sm" in a frame's footer row. Because the 26px cells sit in a 40px row with clear space.
Never: Hide Previous on the first page or Next on the last. Because the row would shift, and the person aiming at Next would hit a number.

5 states, highest first

4 checks

: A nav named "Pagination"; the current page has aria-current="page".
: Every page link is named "Page n"; Previous and Next keep their names when only the arrow shows.
: The current page is text-1 on the selection wash at 16.4:1 and 11.7:1; the others text-2 at 7.8:1.
: A disabled link has aria-disabled and no href, so it leaves the tab order.

2 keys

5 edge cases

Page 1 of 1,204: Seven slots, each as wide as "1,204", so Next never moves.
Phone, 390 wide: Previous and Next become arrows; if the numbers still do not fit, "Page 4 of 24".
Cursor API: Previous, "Page 3" and Next.
Right to left: The arrows mirror and the pages run right to left.
Inside a flex row: It measures its own width, so give it one (w-full or a basis); it has no width from its content.

7 props

PaginationNav page: number
PaginationNav pages: number
PaginationNav hasNext: boolean
PaginationNav getHref, hrefPattern: function, string default '?page={page}'
PaginationNav onPageChange: (page, event) => void
PaginationNav size: 'default' | 'sm' default 'default'
PaginationInfo from, to, total, noun: number, number, number, string

13 tokens