Radio
A binary input, part of a single-select group.
Typical use 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.
The v-model
value is the inputValue
of the Radio that is currently on.
Demos
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 #description
slot.
This demo uses the Field component—usage of this component is described in the next section.
Name | Value |
---|---|
View | |
Reading direction |
Form field
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 isFieldset
to true
to ensure proper accessibility support. This wraps the group in a <fieldset>
element and labels it with an associated <legend>
.
If using a Radio group outside of a form, follow the instructions in the next demo.
Radio group
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
role="radiogroup"
- Connect the group with a label via the
aria-labelledby
attribute
Radio group value: radio-2
Inline radios
Use the inline
prop to get an inline layout.
With no initial selection
Radio group value:
Usage
Props
Prop name | Description | Type | Default |
---|---|---|---|
modelValue | Value of the currently selected radio. Provided by v-model binding in the parent component. | string|number|boolean | '' |
inputValue | HTML "value" attribute to assign to the input. Required for input groups. | string|number|boolean | false |
name (required) | HTML "name" attribute to assign to the input. | string | |
disabled | Whether the disabled attribute should be added to the input. | boolean | false |
inline | Whether the component should display inline. By default, display: block is set and a margin exists between sibling components, for a stacked layout. | boolean | false |
Events
Event name | Properties | Description |
---|---|---|
update:modelValue | modelValue string|number|boolean - The new model value | Emitted when modelValue changes. |
Slots
Name | Description | Bindings |
---|---|---|
default | Label text. | |
description | Short description text. |
CSS-only version
Markup structure
The structure below can be used for most cases. If you need a description, see the section on that feature below.
With description
To add a description below the label:
- Add a span after the
<label>
element with an ID and classcdx-label__description
. Include the description text here. - Add class
cdx-label__label
to the<label>
element - Wrap the label and description in a div with classes
cdx-radio__label
andcdx-label
- Add an
aria-describedby
attribute to the<input>
element with the value of the ID of the description
Radio group
Native attributes of the <input>
element can be used. For example:
- Add the
checked
attribute to the<input>
element if it should be selected initially. - Add the
disabled
attribute 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<fieldset>
and<legend>
. - If using the Radio group outside of a field, wrap the group in a
<div>
withrole="group"
andaria-labelledby
set 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).
Inline radios
Add the cdx-radio--inline
class to the root element to get an inline layout.