Radio

Usage

• Use Radio for a group where exactly one option must be selected and the selection cannot be deselected once made.
• Use Checkbox instead when zero or more options can be selected independently, or selections need to be unselected.
• Use Toggle instead for an on/off setting that takes effect immediately, without form submission.
• Use Radio to show every option at once in a vertical list — best for two to seven options, especially when options need descriptions.
• Use Select instead once the list grows longer than Radio can comfortably show.
• Use SegmentedControl instead to switch the view of adjacent content, not to collect a form answer.
• Wrap related Radios in a RadioGroup so they share a single label and can have their disabled state toggled together.

Behaviors

• Disabled state (isDisabled) prevents interaction; a disabled selected Radio uses muted colors.
• Danger/error state (isInvalid + error) applies danger styling to the assistive text while the radio input itself stays unchanged. isInvalid alone does not render a message — pair it with error.
• Truncation (shouldTruncateLabel) clips a long label to a single line with an ellipsis instead of the default wrapping behavior. When enabling it, put the most important part of the label first since the end may be cut off.
• A Radio cannot be deselected by the user. If "none of these" is a valid answer, add an explicit option for it in the group rather than relying on deselection.
• Preselect the safest or most common option in a required group. Do not leave a required group with nothing selected.
• Keep a group to seven options at most; use Select for longer lists.
• Stack Radio options vertically by default. Only use a horizontal layout for one- to two-word labels with no description.
• An option can reveal a dependent control (e.g. a TextField or Select) below its label. Keep that control disabled until its option is selected, and indent it to align with the label text, not the Radio itself.

Content

• Label the RadioGroup with the question the options answer, so each option label can stay short instead of repeating context.
• Write option labels in sentence case with no end punctuation, using a consistent grammatical shape across every option in the group. State what the option does rather than how it's implemented.
• Use description for short, complete sentences that help the user choose — hints, formatting guidance, or constraints. Apply it consistently: if one option in a group has a description, every option should.
• Use error for direct instructions on what the user must fix, not just that something is wrong. Never use "Please".

Implementation Notes

• Rich label content: React passes a node directly to label. Ember passes rich content through the label named block instead of @label (plain-text labels can still use @label directly).
• Inside a RadioGroup, omit isChecked and name on each Radio — the group's context supplies both (context takes precedence when present). Set them directly only on a standalone Radio used outside a group.
• Always set value on each Radio in a group — it's what RadioGroup matches against to derive isChecked and what its onChange receives.
• On a standalone Radio, onChange is deprecated in favor of onCheckedChange, which is called with (checked, event) instead of a raw change event. Inside a RadioGroup, set onChange on the group instead — it's the group's only change handler and is called with (value, event).
• Assistive text renders description and error together when both are set — an error does not suppress or replace the description text.