Components · Form

Radio button

A radio button lets the user choose exactly one of two or more mutually exclusive options. Choosing one clears the others in the group.

Every example on this page is the real component, not a picture. Click, tab and use the arrow keys to try it. Figma: Radio Button.

Playground

Choose a breakpoint, size, state and value and the radio and its code update. Hover and focus are forced here so they can be seen. The radio is live: click it.

Breakpoint
Size
State
Value

Markup for this selection

HTML




Overview
A radio button lets the user choose exactly one of two or more mutually exclusive options. Choosing one clears the others in the group.
Radio has two sizes (Large, Small), eight states and an optional hint message under the label. It is a native <input type="radio">, so grouping and arrow-key navigation come from the browser.
This documentation has three pages. Examples & Guidelines (this page) shows when and how to use a radio button. Specifications holds the values: tokens, sizes, measurements, states and requirements. Code shows how to add one to a page.




Usage
When to use
Use radio buttons when the user picks exactly one option from a short list and all options should be visible at once. Use them to:
  • Present two or more mutually exclusive options where the user must pick exactly one
  • Choose a delivery method, a payment type or a size from a short list
  • Answer a yes/no question that is saved when the form is submitted
Preselect a default option in every group unless the user must choose consciously. It removes confusion and gives users a clear suggestion.
When not to use
Radio button or checkbox
A radio group allows only one choice. When several options can be chosen, use eco-checkbox.
Do use radio buttons when only one option can be chosen.
Do not use checkboxes for a choice between options. Use radio buttons instead.
Always preselect a default
Preselect one option in every group unless the user must choose consciously. It removes confusion and gives users a clear suggestion.
Do preselect a default option.
Do not leave a group without a default.
Stack the options
Stack options vertically: it is easier to scan. Horizontal only for two short options.
Do stack options vertically.
Do not lay out more than two options horizontally.
For a setting, a view or a long list
For a setting that applies at once, use eco-switch. To switch between two related views or filters in the same surface, use eco-pill-segment-control. For one value from a long list, use eco-select.
Quick reference
The user…Use
picks exactly one of two or more optionsRadio
picks any number of options, saved on submiteco-checkbox
turns one setting on or off, with immediate effecteco-switch
switches between two related views or filterseco-pill-segment-control
picks one value from a long listeco-select
Do
  • Preselect a default option in every group.
  • Stack options vertically and wrap input and text in one label.
  • Give the group a legend.
  • Use Small only in dense layouts.
Don’t
  • Use radios for multi-select. Use checkboxes instead.
  • Lay out more than two options horizontally.
  • Draw the circle with an image or SVG file.
  • Hardcode colors: use the tokens.




Anatomy
Radio button
  1. Area. 24×24px: the circle plus a 4px margin. The margin leaves exactly room for the focus ring (2px gap plus 2px line), so focusing never shifts the layout.
  2. Circle. 16px with a 1px border (14px in Small).
  3. Dot. 6px, drawn as a radial gradient. It shows when the radio is selected.
  4. Label. body-md (Large) or body-sm, 8px from the circle. The whole label is the click target.
  5. Message. Optional hint, body-sm, text-tertiary, 4px below the label.




Variants
Radio buttons are used in groups. The patterns below show the group with a default, the optional hint message and a disabled group. Use the Breakpoint toggle to preview the Large label on desktop (17/24) and mobile (16/22).
Breakpoint
Group with a default
Related options sit in a fieldset with a legend, stacked vertically, with one option preselected. A hint message sits under the label of the option it explains.
Disabled
A disabled group keeps the selection visible.




Sizes
Large is the default. Small (class .form-radio-item--sm) is for dense layouts. The size does not change with the breakpoint; only the Large label does. Measurements are under Sizes in Specifications.




Layout & Appearance
Orientation
Stack options vertically: it is easier to scan. Horizontal only for two short options: it hides the link between radio and label for longer lists.
Appearance
A radio is a 16px circle with a 1px grey border. When it is selected the border turns black and a 6px dot appears. Token names and values are under Design Tokens in Specifications.




Behavior
Selecting
A click on the circle or the label selects that option and clears the others in the group.
Hover and focus
Hover gives the circle a grey fill and a darker border. The focus ring shows with :focus-visible only. All states are listed under States in Specifications.
Default
Preselect one option in every group unless the user must choose consciously.
Disabled
A disabled radio is not focusable. It has a grey fill, a light border and a text-disabled label and message.




Accessibility
All requirements are listed under Accessibility Requirements in Specifications.
Keyboard support
Tab enters the group once, on the selected radio or on the first one. The arrow keys move to and select the next or previous option. This works when every radio shares one name.
Screen reader support
Put the group in a fieldset with a legend, so the question is read together with each option. Wrap the input and the text in one label.







References