> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK /dev/sdks/python/index.md; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; Aura UI /cdf/aura/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Pagination

> Pagination helps users navigate large sets of data by dividing them into manageable pages. It allows for faster load times, better user control, and easier data scanning.

<Badge color="blue">v1.0.0</Badge> | [View in Storybook](https://master--695bb4b1b8041ae09768950a.chromatic.com/?path=/docs/primitives-pagination--docs)

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-pagination--sizes" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-pagination--sizes&viewMode=story&globals=theme:light" title="Pagination sizes story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

## 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](/cdf/aura/primitives/segmented-control) or [Tabs](/cdf/aura/primitives/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](/cdf/aura/primitives/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](/cdf/aura/primitives/data-grid) or long lists; "rows per page" [Select](/cdf/aura/primitives/select); prev/next [Button](/cdf/aura/primitives/button)s; preserve active [Search](/cdf/aura/primitives/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.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-pagination--with-results-per-page" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-pagination--with-results-per-page&viewMode=story&globals=theme:light" title="Pagination with results per page story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Teleportation mode

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

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-pagination--teleportation-mode" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-pagination--teleportation-mode&viewMode=story&globals=theme:light" title="Pagination teleportation mode story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Teleportation widths

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

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-pagination--teleportation-widths" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-pagination--teleportation-widths&viewMode=story&globals=theme:light" title="Pagination teleportation widths story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Disabled

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

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-pagination--disabled" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-pagination--disabled&viewMode=story&globals=theme:light" title="Pagination disabled story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Accessibility

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

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-pagination--accessibility" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-pagination--accessibility&viewMode=story&globals=theme:light" title="Pagination accessibility story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

### Edge cases

Handle edge cases such as the first page, last page, single-page results, and filtered empty sets so controls stay predictable.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-pagination--edge-cases" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-pagination--edge-cases&viewMode=story&globals=theme:light" title="Pagination edge cases story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>