Radio Button
Last Updated: September 2026Radio button groups let users pick exactly one option from a short visible set of mutually exclusive choices.
Source CodeAnatomy
link- 1Group
- 2Control
- 3Label
Variants
linkDefault
Labeled items in a vertical group; one value selected.
Horizontal
Override the group layout with flex-row for compact choices.
Disabled item
Disable individual options while keeping the group interactive.
Without label
Control-only — pair with an external label or aria-label.
Usage Guidelines
linkWhen to use
- •When the user must pick exactly one option from a short, visible list.
- •For settings where all choices should stay on-screen for easy comparison.
- •When mutually exclusive options are clearer as radios than as a Select.
When not to use
- •For multi-select — use Checkbox.
- •For long option lists — use Select or Combobox.
- •For immediate on/off settings with a track affordance — use Switch.
Use a radio group when users should compare a small set of exclusive options.
Don't use a long radio list — prefer Select or Combobox.
Keep mutually exclusive choices as radios; independent toggles as checkboxes.
Don't use checkboxes when only one option can apply.
Behaviors
linkValue model
- •Uncontrolled: defaultValue on RadioGroup.
- •Controlled: value + onValueChange on RadioGroup.
- •Each Item needs a unique value within the group.
Label wrapping
- •When label is set, control + typography share one clickable <label> row.
- •className applies to the wrapper when labeled; to the control when label is omitted.
Disabled
- •disabled on an Item blocks that option and uses the disabled palette.
- •Hover styles never override disabled.
Content Guidelines
linkLabels
- •Use parallel phrasing across options (“Day / Week / Month”).
- •Keep labels short enough to scan in a vertical or horizontal group.
Accessibility
linkText & Labels
- •Prefer the label prop so the whole row is activatable.
- •Without label, provide aria-label on each Item.
ARIA attributes
- •Built on Base UI Radio Group — exposes radiogroup / radio roles and checked state.
- •Disabled items are not operable and announce as disabled.
Keyboard Support
- •Tab → focus the selected (or first) radio in the group.
- •Arrow keys → move selection within the group.
- •Space → select the focused radio.
WCAG Compliance Standards
FAQs
linkRadio vs Checkbox?
Radios for mutually exclusive single choice; Checkboxes when more than one option can be selected.
Radio vs Select?
Use a radio group when the full set should stay visible (usually ≤ ~5 options). Use Select for longer lists.
Radio vs Segmented Control?
Radios suit labeled form choices in a list. Segmented Control suits compact, toolbar-style exclusive picks.
Controlled vs uncontrolled?
Use value + onValueChange when you own state; defaultValue when you don’t need to.