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

# Switch

> A Switch toggles a setting on or off. It represents a binary state and should update immediately when toggled. Switches are typically used for system or feature controls that take effect right away.

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

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

## When to use

* To turn something on or off, like enabling notifications or toggling a setting.
* For immediate actions where changes happen instantly and don't require confirmation (e.g., turning on dark mode).

## When to use something else

* Deferred or form-bound changes: use [Checkbox](/cdf/aura/primitives/checkbox) or explicit [Button](/cdf/aura/primitives/button) submit.
* One-shot actions (delete, submit): use [Button](/cdf/aura/primitives/button).
* Several related on/off settings: use [Toggle group](/cdf/aura/primitives/toggle-group), [Checkbox](/cdf/aura/primitives/checkbox), or [Select](/cdf/aura/primitives/select)—not a single [Switch](/cdf/aura/primitives/switch) per unrelated setting.

## Dos and don'ts

* **Do** use clear descriptive labels to explain what the Switch controls.
* **Don't** use Switches inside Menus to toggle a setting on/off (e.g., "Show grid lines", "Show axis"). Instead, use a toggle menu item that displays a checkmark when something is on and remove the checkmark when something is off.
* **Don't** use Switches for destructive actions.

## Behavior

* Toggles immediately on interaction; state should reflect the backing setting without requiring a separate submit unless the form pattern says otherwise.
* Do not embed [Switch](/cdf/aura/primitives/switch) in [Menu](/cdf/aura/primitives/dropdown-menu) rows; use menu checkmark toggles per guidance above.

## Often used with

[Label](/cdf/aura/primitives/label) (often inline), [Helper text](/cdf/aura/primitives/helper-text) when the setting needs explanation; not inside [Menu](/cdf/aura/primitives/dropdown-menu) rows—use menu checkmarks instead.

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

### Default checked

Use a default checked switch when the setting should start enabled—for example, notifications on by default or a commonly preferred display option.

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

### Disabled

Use a disabled switch when the setting cannot be toggled, and explain why in helper text or a tooltip so users know what must happen before they can change it.

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

### Controlled

Use a controlled switch when on/off state must follow application logic—for example, syncing with a parent form, feature flags, or programmatic enable and disable.

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

### Settings form

Group switches in a settings form when users configure multiple related preferences—for example, notification types, display options, or feature toggles.

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

### Without visible label

Use a switch without a visible label only when the purpose is clear from surrounding context, and always provide an accessible name for screen readers.

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

### All states

Review all switch states together to ensure checked, unchecked, disabled, and focus styles remain clear and consistent across your settings UI.

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