Build Assets
UI Component
Radio Button Group
Mutually exclusive single-choice selector where all options are visible simultaneously.
Platform: bothTags: radio, form, choice, selection, input
Purpose
When users must choose exactly one option from 2–5 visible choices. Showing all options simultaneously helps users make an informed decision. More than 5 options: use a dropdown.
Anatomy
- Group label: 14px semibold above the options
- Radio button: 18×18px circle, 2px border
- Selected state: filled inner circle (10px) in accent color
- Item label: 14px to the right of the radio, clickable area
- Optional description: 13px secondary text below label
- Error message: 13px red below the group
States
- Unselected: empty circle with grey border
- Selected: outer circle accent border, filled inner disc
- Focused: visible focus ring around the radio + label
- Disabled: 40% opacity
- Error: red border on all options, error message below group
Tokens
spacing
itemGap: 12pxlabelGap: 8pxgroupGap: 16px
sizing
radioSize: 18pxinnerDisc: 10px
Do
- Always have one option selected by default when there's a sensible default
- List options in a logical order (most common first, or alphabetical)
- Make the entire row (radio + label) the click target
- Use for 2–5 options where all choices benefit from being visible
Don't
- Use radio buttons for more than 5 options — use a dropdown
- Use when multiple selections are allowed — use checkboxes
- Stack radio groups horizontally if labels are longer than 2 words
- Use "None" as the default selection when another option is more appropriate
Accessibility
- role="radiogroup" on the container with aria-labelledby pointing to group label
- Each radio: <input type="radio"> or role="radio" with aria-checked
- Arrow keys navigate within the group (not Tab)
- Tab moves focus to the selected radio in the group (not each option)