Radio

Usage

Overview

Radio lets operators pick exactly one option from a mutually exclusive set. The classic control is compact; see RadioCards for rich single-select with descriptions. The mental model is "pick one alternative"—not "toggle features on" and not "choose from a long list". Radio is the right shape when the full set fits comfortably in the layout and scanning beats opening a dropdown.

Audio SIP assignment

ExtensionAliasNo assignment

When to use

Two to roughly seven visible options where seeing all choices at once aids comparison.
Mutually exclusive settings—plan tier, priority level, primary contact method, sort order.
Forms where validation requires an explicit selection and empty is invalid.

When not to use

Multiple simultaneous selections—use Checkbox or CheckboxCards.
Binary on/off for a single setting—use Switch when that's the product pattern.
Long lists—use Select or Combobox.
Secondary choice inside a menu trigger—use Menu radio items.

Composition

RadioGroup owns the selection state; each RadioGroupItem renders an indicator, a label, and optional helper text. Keep indicators aligned, labels parallel, and the group's accessible name explicit via the fieldset/legend pattern or aria-labelledby.

Content guidelines

Parallel labels that don't overlap in meaning ("Standard", "Priority", "Critical"). Each label should stand alone as a complete option.
Descriptions (in card form) are one short sentence; avoid repeating the title.
Group labels are needed when the question isn't obvious from individual labels—they're also the programmatic accessible name.
Preselect a safe, common choice when one exists; omit the default when regulation or ethics require explicit consent (opt-in vs. opt-out).
Localize all labels and descriptions; longer languages may force cards to stack vertically.

Behavior and states

Selection. Only one active at a time. Clicking the selected option should not clear it unless the product explicitly allows "no selection" and that state is reachable elsewhere.
Disabled options. Explain why nearby or in helper text when the reason matters to the operator.
Keyboard. Arrow keys move the selection within the group per native expectation; Tab enters and exits the group as a single stop.

Best practices

Keep the full set visible without scrolling when counts are small.
Align indicators consistently within a flow (always leading, or always trailing—pick one per surface).
Use radio cards when an option needs a second line of consequence.

Don't

Use radio for navigation between pages. Tabs or a sidebar is the right pattern for that.
Mix radio with checkboxes in the same visual group without clear grouping. The mental models collide.
Hide the selected state only by color. Ensure the shape or indicator conveys state independently of theme.

Accessibility

The group needs an accessible name; focus order matches visual order; selected state is exposed via native semantics. See Accessibility for the full contract.

Radio cards for rich single-select with description.
Checkbox for multi-select.
Segmented control for short, always-visible exclusive modes.
Select for long single-select lists.

Queue / Accessibility

Radio / API and Development

On this page

Radio

Usage

Overview

Audio SIP assignment

ExtensionAliasNo assignment

When to use

Two to roughly seven visible options where seeing all choices at once aids comparison.
Mutually exclusive settings—plan tier, priority level, primary contact method, sort order.
Forms where validation requires an explicit selection and empty is invalid.

When not to use

Multiple simultaneous selections—use Checkbox or CheckboxCards.
Binary on/off for a single setting—use Switch when that's the product pattern.
Long lists—use Select or Combobox.
Secondary choice inside a menu trigger—use Menu radio items.

Composition

Content guidelines

Parallel labels that don't overlap in meaning ("Standard", "Priority", "Critical"). Each label should stand alone as a complete option.
Descriptions (in card form) are one short sentence; avoid repeating the title.
Group labels are needed when the question isn't obvious from individual labels—they're also the programmatic accessible name.
Preselect a safe, common choice when one exists; omit the default when regulation or ethics require explicit consent (opt-in vs. opt-out).
Localize all labels and descriptions; longer languages may force cards to stack vertically.

Behavior and states

Selection. Only one active at a time. Clicking the selected option should not clear it unless the product explicitly allows "no selection" and that state is reachable elsewhere.
Disabled options. Explain why nearby or in helper text when the reason matters to the operator.
Keyboard. Arrow keys move the selection within the group per native expectation; Tab enters and exits the group as a single stop.

Best practices

Keep the full set visible without scrolling when counts are small.
Align indicators consistently within a flow (always leading, or always trailing—pick one per surface).
Use radio cards when an option needs a second line of consequence.

Don't

Use radio for navigation between pages. Tabs or a sidebar is the right pattern for that.
Mix radio with checkboxes in the same visual group without clear grouping. The mental models collide.
Hide the selected state only by color. Ensure the shape or indicator conveys state independently of theme.

Accessibility

The group needs an accessible name; focus order matches visual order; selected state is exposed via native semantics. See Accessibility for the full contract.

Radio cards for rich single-select with description.
Checkbox for multi-select.
Segmented control for short, always-visible exclusive modes.
Select for long single-select lists.

Queue / Accessibility

Radio / API and Development

On this page