Chapter 27: Radio Group

Core Idea

A set of mutually-exclusive checkable buttons — the multi-option counterpart to Checkbox, with full roving-tabindex keyboard navigation between options.

Key Concepts

• Anatomy: Root → Item (per option, → Indicator rendered when checked).
• loop (default true): whether arrow-key navigation wraps from the last item back to the first.
• Form compatibility: like Checkbox, each Item renders a hidden native input automatically for form submission.
• orientation: affects which arrow keys move focus between items (vertical → Up/Down, horizontal → Left/Right).

Code Examples

<RadioGroup.Root defaultValue="default" aria-label="View density">
  <RadioGroup.Item value="default" id="r1">
    <RadioGroup.Indicator />
  </RadioGroup.Item>
  <label htmlFor="r1">Default</label>
</RadioGroup.Root>

• What it demonstrates: pairing each Item with a native label/htmlFor for click-to-select, since Item itself doesn't render a label.

Reference Tables

Part	Key props	Key data attributes
Root	value/defaultValue, onValueChange, disabled, name, required, orientation, loop (default true)	[data-disabled]
Item	value, disabled, required	[data-state] (checked|unchecked), [data-disabled]

Key Takeaways

1. Reach for RadioGroup over a set of independent Checkboxes whenever selection is mutually exclusive — you get correct roving-tabindex arrow-key navigation for free.
2. Always associate a visible label with each Item (via htmlFor/id or wrapping) — Item provides no text content itself.
3. loop defaults to true, unlike some other Radix collections — disable it explicitly if wrap-around navigation is undesired.

Connects To

• Checkbox: the independent-toggle counterpart to this mutually-exclusive selection primitive.
• Toggle Group: a different mutually-exclusive (or multi-select) pattern for button-styled options instead of radio dots.