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

# Toggle group

> A set of mutually exclusive options where one or multiple can be selected. Use it for toggling on settings, such as grid lines, rulers, or text formatting options like bold, italics, underline, etc.

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

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

## When to use

* 2–4 options that are mutually exclusive and always visible.
* The current selection needs to be immediately obvious.

## When to use something else

* More than \~4–5 options: use [Select](/cdf/aura/primitives/select) or [Menu](/cdf/aura/primitives/dropdown-menu).
* Options fire one-off commands: use [Button](/cdf/aura/primitives/button) or grouped buttons, not a [Toggle group](/cdf/aura/primitives/toggle-group).
* Multi-select filters: use [Checkbox](/cdf/aura/primitives/checkbox) or filter chips ([Badge](/cdf/aura/primitives/badge) / closeable patterns).
* Single-select filter of a small set: use [Segmented control](/cdf/aura/primitives/segmented-control).
* Page navigation: use [Tabs](/cdf/aura/primitives/tabs) or routing, not [Toggle group](/cdf/aura/primitives/toggle-group).

## Dos and don'ts

* **Do** keep labels short — one or two words per option or use icons only.
* **Don't** mix icons and text labels across options in the same group — be consistent.

## Behavior

* Selection updates immediately; supports single or multi-select per configuration. Do not use for destructive one-shot actions without confirmation.

## Often used with

[Toolbar](/cdf/aura/primitives/toolbar) formatting tools; [Tooltip](/cdf/aura/primitives/tooltip) when icon-only; mutually exclusive or multi-select state next to the canvas or preview it affects.

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

### Outline

Use the outline variant when toggle buttons should read as distinct, bordered controls—for example, formatting tools in a toolbar or view options in a compact row.

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

### All variants

Compare toggle group variants to choose the style that best matches surrounding controls—default, outline, and ghost each suit different density and emphasis levels.

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

### Composed content

Combine icons and labels within toggle items when both improve clarity—for example, text formatting options where the icon reinforces the label.

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

### Sizes

Choose the size that matches surrounding controls—use smaller toggles in dense toolbars and larger toggles when the group is a primary control.

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

### Controlled

Use a controlled toggle group when selection must follow application logic—for example, syncing with canvas state, URL parameters, or a parent settings panel.

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

### Accessibility

Ensure toggle items expose pressed state to assistive technologies, support keyboard navigation between options, and provide accessible names for icon-only toggles.

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

### Disabled

Disable individual toggles or the entire group when options are temporarily unavailable, and explain why in a tooltip or helper text.

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

### Edge cases

Review edge cases—such as single-item groups, all-disabled states, or overflow—to ensure the toggle group remains usable in constrained layouts.

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