Radio
For choosing just one option when all of them fit on screen.
Examples
Checked
falsedefault
true
States
rest
hover
focus-visible
disabled
Usage
When to use it
- Use
- One of 2 to 6 options where seeing them all helps: a quality, a plan, a privacy level.
- Use
- Options that need a line of explanation beside each.
- Not for
- More than about six options. Use Select.
- Not for
- A view switch that applies at once. Use Segmented.
- Not for
- Any number of options may be on. Use Checkbox.
Rules
8 rules
- Must
- Put radios in a RadioGroup with an aria-label or a visible label. Because the arrow keys and the single choice live in RadioGroup, and its name is read on entry.
- Must
- Wrap the circle and its text in one label element. Because a loose span leaves the 20px circle as the only tap target and the radio unnamed.
- Should
- Set defaultValue when one option is safe; a chosen group cannot be cleared.
- Should
- Write options in the same shape with the cost or difference last.
- Never
- Style one-line options as large cards; use rows unless each needs a paragraph. Because cards for three one-line choices push Continue below the fold on a phone.
- Must
- Use Select past about six options. Because each radio is a full row, so twelve of them push the rest of the form off the screen.
- Must
- Say what is missing in text beside the group. Because Radio has no invalid style, so nothing else tells the person a choice is needed.
- Should
- Use items-start on a label row that wraps, so the circle stays by the first line.
Accessibility
5 checks
- RadioGroup is role radiogroup and needs a name; each Radio is role radio named by its label.
- Tab enters the group once; arrows move and choose; Space chooses the focused radio.
- Focus shows a 2px olive ring around the circle.
- The 20px circle is under 44px; the wrapping label makes the line the target.
- Forced colors paints a chosen circle Highlight and the dot HighlightText.
Edge cases
6 edge cases
- Long label
- Wraps beside the circle; use items-start so it stays by the first line.
- Right to left
- The circle moves to the right edge; arrows follow the reading direction.
- Chosen and hovered
- The lime fill stays; the edge darkens under the pointer.
- Many options
- The column grows; switch to Select.
- Inside a form
- The chosen value submits under the group name.
- Reduced motion
- Colors change at once.
API
5 props
RadioGroup value, defaultValuestringRadioGroup onValueChange(value: string, details) => voidRadioGroup name, disabled, requirednativeRadio valuestringdefaultrequiredRadio disabledbooleandefaultfalse
Tokens
14 tokens
--page- #ffffff
--control- #85827a
--fg-2- #4a4943
--accent- #e4f222
--accent-line- #7c8700
--on-accent- #0f0f0d
--line-strong- #cfcdc6
--surface-2- #efeeea
--fg-disabled- #a6a49b
--ring- var(--accent-line)
--line-focus- 2px
--focus-offset- 2px
--dur-fast- 140ms
--ease-out- cubic-bezier(0.16, 1, 0.3, 1)