Skip to main content
v1.0.0 | View in Storybook

When to use

  • When there is a large dataset or long lists (tables, search results, item galleries).
  • When performance or load times could be impacted by infinite scroll.
  • When users need to reference or return to specific locations in a dataset.

When to use something else

  • Continuous, discovery-focused feeds: prefer infinite scroll or “Load more.”.
  • Task completion requires consuming items in order: use wizards or dedicated flows instead of arbitrary page jumps.
  • Switching unrelated page modes: use Segmented control or Tabs instead of page numbers.

Dos and don’ts

  • Do provide “Next” and “Previous” Buttons as these provide intuitive navigation for sequential browsing. Disable the “Next” and “Previous” Buttons if not relevant.
  • Do provide “Results per page” options for large data sets. This lets users control how much data they see at once.
  • Do place Pagination below the Data grid (or page content), left aligned. This ensures side panels opening from the right will not overlap the Pagination.
  • Do use the “results” section to indicate the number of items per page by default or when filtered.
  • Do show a teleport when there are large datasets to help the user navigate to a specific page.
  • Don’t use Pagination when there are fewer than ~20 items per page as this can be cumbersome for the user.

Behavior

  • Ideally, every page should have its own URL so that links to specific pages can be bookmarked or shared.
  • If possible, items on each page should load without reloading the entire page. Use a loader and skeletons to indicate that content is loading.
  • Consider loading times when deciding whether to use Pagination or other alternatives such as lazy loading.
  • When the teleport variation is being used, the user can navigate to a desired page by typing the page number and pressing Enter on the keyboard.
  • If there are filters, selection, or search, preserve those as the user moves across pages.

Often used with

Data grid or long lists; “rows per page” Select; prev/next Buttons; preserve active Search / filters across pages.

Visual examples

The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

With results per page

Let users change how many rows appear per page when datasets are large enough that page size meaningfully affects scanning and performance.

Teleportation mode

Use teleportation when users may need to jump directly to a distant page in very large datasets instead of clicking through sequentially.

Teleportation widths

Adjust teleport input width to accommodate the expected page-number length without clipping or leaving excessive empty space.

Disabled

Disable pagination controls when there is only one page of results or while data is loading to prevent invalid navigation.

Accessibility

Ensure page controls expose clear labels, keyboard support, and current-page state so assistive technologies can announce position in the dataset.

Edge cases

Handle edge cases such as the first page, last page, single-page results, and filtered empty sets so controls stay predictable.
Last modified on September 16, 2026