Pagination

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Usage

Let people browse same-kind results page by page. Place it after the list. Use onPageChange for in-page state, or getPageHref for real URL navigation. The current page has aria-current=page.

• Don't split short lists. Show the whole list instead.
• Don't use it for step-by-step input flows. Use the form's own Back and Next actions instead.
• Don't request a page that became invalid after a filter change. Clamp page to the new pageCount instead.
• Don't invent a total page count when cursor-based navigation can't know it. Use plain Previous and Next buttons instead.

Size: SizeProvider size="small" resizes the whole composition, including portals. The default size is Default. Size guidance and comparisons

Anatomy

named nav → Previous control + list(page controls / decorative SVG gaps) + Next control

Keyboard and accessibility

• Tab moves between the controls.
• Enter activates the controls, and buttons also respond to Space. Links keep browser behaviors such as opening in a new tab.
• Pagination renders nothing when there's one page or fewer. On small screens, it shows Previous, Next, and a current/total page summary.
• The caller decides how results are announced, how loading shows, and where focus goes after a page change.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { Pagination } from '@surflane/ui'

<Pagination
  page={page}
  pageCount={pageCount}
  onPageChange={setPage}
  aria-label='Pipeline run pages'
/>

<Pagination
  page={2}
  pageCount={10}
  getPageHref={(page) => `/runs?page=${page}`}
/>

Key API

The table lists the common wrapper's main props. See the package type declarations for the full types.

Related tokens