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

# Radio

> Radio buttons allow users to select one option from a list of mutually exclusive choices. Once a selection is made, it typically persists until the user selects a different option.

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

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

## When to use

* When users need to make a single selection from a small set of predefined options.
* When it's important that all options are immediately visible, helping users compare choices side by side.
* When the options are mutually exclusive (only one can be selected at a time).

## When to use something else

* Multiple selections: use [Checkbox](/cdf/aura/primitives/checkbox).
* More than \~five options or tight space: use [Select](/cdf/aura/primitives/select) or [Combobox](/cdf/aura/primitives/combobox).
* Binary on/off with immediate effect: use [Switch](/cdf/aura/primitives/switch).
* Long lists with search: use [Combobox](/cdf/aura/primitives/combobox).

## Dos and don'ts

* **Do** pair with a label that describes what the user is selecting.
* **Do** use the radio button group to group related options.
* **Don't** use the radio button group to group unrelated options.
* **Don't** use the radio button group to group more than five options.
* **Don't** use the radio button group when the options are not mutually exclusive.

## Radio vs Radio + card

* Use a plain radio button when the options are simple labels and the choice doesn't need much explanation — a list of sizes, a frequency, etc...
* Use the card container when:
  * Each option needs supporting text or a description to be understood.
  * The options represent meaningfully different paths (e.g. plan tiers, configuration modes, templates, roles).
  * The visual weight of the choice should match its importance in the flow.
  * The card makes each option feel like a distinct selection rather than an item in a list — that framing is only appropriate when the options are genuinely distinct and the user needs to consider them, not just pick one quickly.

Don't use the card variant just to add visual interest to a simple choice. The extra weight implies the decision is more complex than it is, which slows users down.

## Often used with

Group [Label](/cdf/aura/primitives/label) / legend, per-option [Label](/cdf/aura/primitives/label), [Helper text](/cdf/aura/primitives/helper-text); [Card](/cdf/aura/primitives/card) variant for heavy options.

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

Add a description under each option when users need supporting text to understand the difference between choices.

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

### Horizontal

Lay out radio options horizontally when labels are short and comparing choices side by side speeds selection.

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

### Card

Use the card variant when each option represents a distinct path that benefits from a title, description, and stronger visual weight.

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

### Horizontal cards

Arrange card options in a row when there are few choices and horizontal space allows users to compare plans, tiers, or modes at a glance.

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

### Disabled

Disable individual options or the entire group when a choice is unavailable in the current context, with helper text explaining why.

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

### States

Review default, hover, focus, selected, and disabled states together to keep interaction feedback consistent across the radio group.

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

### Accessibility

Ensure each radio is associated with a [Label](/cdf/aura/primitives/label) and the group has a legend so screen readers announce the set and current selection.

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

### Controlled

Use a controlled radio group when selection must follow application state—for example, syncing with URL parameters or a multi-step wizard.

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

### In form

Place radio groups inside forms with a group label and optional [Helper text](/cdf/aura/primitives/helper-text) so the choice is clear in the broader field layout.

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