Radio lets operators pick exactly one option from a mutually exclusive set. The classic control is compact; see RadioCardGroup 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.
- 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.
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.
- 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.
- 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.
Do
- 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.
The group needs an accessible name; focus order matches visual order; selected state is exposed via native semantics. See Accessibility for the full contract.
