Radio

v1.0.0 | View in Storybook

​

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.
• More than ~five options or tight space: use Select or Combobox.
• Binary on/off with immediate effect: use Switch.
• Long lists with search: use 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 / legend, per-option Label, Helper text; 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.

​

Horizontal

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

​

Card

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

​

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.

​

Disabled

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

​

States

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

​

Accessibility

Ensure each radio is associated with a Label and the group has a legend so screen readers announce the set and current selection.

​

Controlled

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

​

In form

Place radio groups inside forms with a group label and optional Helper text so the choice is clear in the broader field layout.