> ## 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.

# Tabs

> Tabs help users organize and navigate between sections of related content without leaving the page. They provide an efficient way to display different views or categories of information in the same context.

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

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

## When to use

* To organize content into sections that users need to switch between frequently.
* When sections are related and share the same context.
* To display mutually exclusive content without overwhelming the user.
* For navigation within a page or primitive (e.g., dashboards, settings, data views).

## When to use something else

* Simple data filtering: use [Segmented control](/cdf/aura/primitives/segmented-control) or a filter [Button](/cdf/aura/primitives/button) with [Menu](/cdf/aura/primitives/dropdown-menu).
* User must see multiple sections at once: keep one page and use [Accordion](/cdf/aura/primitives/accordion) or filters—not mutually exclusive [Tabs](/cdf/aura/primitives/tabs).
* Binary on/off: use [Switch](/cdf/aura/primitives/switch).

## Dos and don'ts

* **Do** use a minimum of two Tab buttons.
* **Do** be mindful of persistent and non-persistent CTAs when using Tabs. Content above Tabs should remain the same across Tabs.
* **Don't** use for binary options.
* **Don't** use Tabs for basic filtering functionality.
* **Don't** be inconsistent with leading icon usage. If using in one, use them in all.

## Placement & alignment

Placement:\
Tabs are typically placed at the top of a page or section, often within the main content area, Topbar, or side panels. Always place Tabs close to the content they control and ensure Tab placement is consistent across pages or flows.

Alignment

* Tabs allow for a default and vertical alignment, which essentially shows or hides label padding on each tab Button. This is similar to how Buttons behave.
* Tabs can also be displayed in full width, where the spacing between tabs adjusts evenly allowing the primitive to fill the parent container's width. Consider the surrounding content and container when deciding which to use. This is best used in side panels or when there are a lot of Tabs that take up the entire width of the container.

## Behavior

* Exactly one tab panel is visible at a time for a given tab set; tab buttons update `aria-selected` / roving focus per implementation.
* Content above the tab list should stay stable across tabs; don't move primary CTAs in ways that disorient users when switching.

## Often used with

Tab panels containing [Data grid](/cdf/aura/primitives/data-grid), forms, [Card](/cdf/aura/primitives/card)s, or [Empty state](/cdf/aura/primitives/empty-state); keep global page actions outside the tab panel when they must not move.

## 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 icon

Add leading icons to tab labels when they help users scan sections quickly—for example, settings, data, or notification views.

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

### Size inheritance

Tab button size inherits from the tab list configuration—match the size to surrounding controls, such as smaller tabs in dense panels or larger tabs in primary navigation.

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

### With badge

Add a badge to a tab when a section has a count or status users should notice—for example, unread items, pending tasks, or new content.

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

### Decorative badge

Use a decorative badge for non-numeric indicators—for example, marking a tab as "New" or "Beta" without implying a specific count.

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

### Full width

Use full-width tabs when the tab list should span its container—for example, in a side panel or when each tab should share equal space across the available width.

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

### Icon only

Use icon-only tabs when space is limited and the icons are widely understood—always pair with tooltips and accessible names so meaning is clear.

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

### Orientation

Choose vertical or horizontal tab alignment based on layout—vertical tabs work well in side panels, while horizontal tabs suit page-level navigation.

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

### Interactive

Use interactive tab examples to verify keyboard navigation, focus management, and panel switching behave correctly in your implementation.

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

### Accessibility

Ensure tab buttons expose correct `aria-selected` state, roving focus works as expected, and each panel is associated with its tab for screen reader users.

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