A Radio is a binary input that is usually combined in a group of two or more options. They signal a pattern where users can only select one of the available options. Radios are also known as “radio buttons”.
Radios must feature a descriptive label. They must be part of a radio group of at least two elements. A radio may also have sub-components or child radio groups.
Use the Radio component to make a single selection from a list of options where only one choice is allowed. When multiple selections are needed, use Checkbox instead.
Radio buttons make the selection visually distinct.
The label text size should match the base font size to ensure consistency withthe body text. It can also include links and bold text. Labels should be as short as possible, and include text that clearly states which selection is being made.
Refer to the Radio component in Codex Figma.
Radio buttons’ states were designed using accessible color variations. In addition to the 'disc' icon, these make it easier to differentiate between the radio button’s selected and unselected modes (e.g. disabled, hover, active):
- Default unselected
- Hover unselected
- Active unselected
- Focus unselected
- Disabled unselected
- Default selected
- Hover selected
- Active selected
- Focus selected
- Disabled selected
The disabled state does not meet our minimum color contrast rules. WCAG 2.1 states that “…part[s] of an inactive user interface component […] have no contrast requirement”.
Provide sufficient information in a disabled element's context, so the user can understand what is disabled and how to enable it (if applicable).
A radio button ensure that a reader chooses only one option from a set of two or more. Keeping choices simple and mutually exclusive makes for concise, effective and trustworthy content.
Open up the browser console to see events emitted on input.
Label and description
Always include label text via the default slot. You can also add description text via the
This demo uses the Field component—usage of this component is described in the next section.
When used in a form, a group of Radios can be wrapped in the Field component to add features like a semantic label, description and help text, validation messages, and more. See the Field page for more information.
When building a Radio field, always set
true to ensure proper accessibility support. This wraps the group in a
<fieldset> element and labels it with an associated
If using a Radio group outside of a form, follow the instructions in the next demo.
For a group of radios, each Radio component's
v-model will be bound to the same ref, which is equal to the
inputValue prop of the selected Radio. Use the same
name prop for all of the Radio components in a group.
This demo shows what to do when using a Radio group outside of a form:
- Wrap the group in an element with
- Connect the group with a label via the
Radio group value: radio-2
inline prop to get an inline layout.
With no initial selection
Radio group value:
Typical use of this component will involve using
v-for to loop through an array of items and output a Radio component for each one. Each Radio will have the same
v-model binding and
name prop, but different
inputValue props and label content.
v-model value is the
inputValue of the Radio that is currently on.
|Value of the currently selected radio.|
|HTML "value" attribute to assign to the input.|
Required for input groups.
|HTML "name" attribute to assign to the input.|
|Whether the disabled attribute should be added to the input.|
|Whether the component should display inline.|
|modelValue ||Emitted when modelValue changes.|
|description||Short description text.|
The structure below can be used for most cases. If you need a description, see the section on that feature below.
To add a description below the label:
- Add a span after the
<label>element with an ID and class
cdx-label__description. Include the description text here.
- Add class
- Wrap the label and description in a div with classes
- Add an
aria-describedbyattribute to the
<input>element with the value of the ID of the description
Native attributes of the
<input> element can be used. For example:
- Add the
checkedattribute to the
<input>element if it should be selected initially.
- Add the
disabledattribute to the
<input>element if it should be disabled.
Always include one of these two features for accessible grouping:
- If using the Radio group in a field, wrap the group in a
<fieldset>element and add a
<legend>element with the group label. This method is demonstrated below and requires some style resets on
<legend>. You can use the CSS-only Field and Label components to reset browser styles of these elements.
- If using the Radio group outside of a field, wrap the group in a
aria-labelledbyset to the ID of the group label. See an example of this above (you can just include a
<label>element instead of using the Label component).
cdx-radio--inline class to the root element to get an inline layout.