Radio

A radio is an input control that allows users to select only one option from a number of choices.

Preview

Usage

Radio buttons are a common way to allow users to make a single selection from a list of options. Since only one radio button can be selected at a time (within the same group), each available choice must be its own item and label. Upon selection of a radio item in a group, the group cannot be easily reset to zero selections.

Do

When users may only choose a single option out of a set of mutually exclusive choices.
If the number of available options can fit onto a mobile screen.
In place of Select element if there are few enough options (e.g. =7) and the design can support it.

Don’t

Consider Checkbox if users may have the option to select more than one.
Consider a Select if you don’t have enough space to list out all available options.
If users should be able to select zero of the options; radio elements are not “uncheckable.” A Checkbox may be warranted.
If there are too many options to display on a single view; consider a Select instead.

Best Practices

Users should be able to tap on or click either the text label or the radio element itself to select an option.
Options that are listed vertically are easier to read than those listed horizontally. Horizontal listings can make it difficult to tell which label pertains to which radio button.
Make sure selections are adequately spaced for touch screens.
Use caution if you decide to set a default value as they cannot be unchecked. Setting a default value can discourage users from making conscious decisions, seem pushy, or alienate users who don’t fit into your assumptions. If you are unsure, leave nothing selected by default.

Variants and Examples

Base Styles

With Description Text

With Validation States

<div>
  <label>
    <div class="d-radio-group">
      <div class="d-radio__input"><input name="ValidationMessageWarning" type="radio" class="d-radio d-radio--warning" value="Validation Message Warning" /></div>
      <div class="d-radio__copy d-radio__label">
        <div>To voicemail</div>
        <div class="base-input__messages d-validation-message__container">
          <div role="status" aria-live="polite" class="base-input__message d-validation-message base-input__message--warning d-validation-message--warning"><p>So they can hear your voice</p></div>
        </div>
      </div>
    </div>
  </label>
</div>
<div>
  <label>
    <div class="d-radio-group">
      <div class="d-radio__input"><input name="ValidationMessageError" type="radio" class="d-radio d-radio--error" value="Validation Message Error" /></div>
      <div class="d-radio__copy d-radio__label">
        <div>To a message (no voicemail)</div>
        <div class="base-input__messages d-validation-message__container">
          <div role="status" aria-live="polite" class="base-input__message d-validation-message base-input__message--error d-validation-message--error">
            <p>Because they probably dont need to leave a message anyway.</p>
          </div>
        </div>
      </div>
    </div>
  </label>
</div>
<div>
  <label>
    <div class="d-radio-group">
      <div class="d-radio__input"><input name="ValidationMessageSuccess" type="radio" class="d-radio d-radio--success" value="Validation Message Success" /></div>
      <div class="d-radio__copy d-radio__label">
        <div>To a team member or room phone</div>
        <div class="base-input__messages d-validation-message__container">
          <div role="status" aria-live="polite" class="base-input__message d-validation-message base-input__message--success d-validation-message--success">
            <p>Because someone else might be able to talk to them.</p>
          </div>
        </div>
      </div>
    </div>
  </label>
</div>

With Slotted Label

With Slotted Description

Classes

Class	Applies to	Description

Accessibility

The best accessibility is semantic HTML. Most screen readers understand how to parse inputs if they’re correctly formatted. When it comes to radio input, there are a few things to keep in mind:

All inputs should have an id attribute.
Associate radio labels with their inputs using the for attribute. This correlates with the radio's id.
If you have a group of related radios, use a fieldset to group them and a legend to title the group. For further information, please visit Gov.UK’s article, "Using the fieldset and legend elements".
If the input is a required field, use the aria-required property and use the validation message for input errors.
Input with validation errors should have aria-describedby with the id of the validation message.
Input with validation errors should have aria-describedby with the id of the validation message.

Vue API

Slots

Name	Description
default	slot for Radio Label
description	slot for Radio Description

Props

Name	Description	Default
description	Describes the input Type: string	''
descriptionChildProps	A set of props that are passed into the description container Type: object	{}
descriptionClass	Used to customize the description container Type: string\|array\|object	''
disabled	Disables the input Type: boolean	false
indeterminate	Indeterminate State, toggling indeterminate checkbox will uncheck Type: boolean	false
inputClass	Used to customize the input element Type: string\|array\|object	''
label	A provided label for the input Type: string	''
labelChildProps	A set of props that are passed into the label container Type: object	{}
labelClass	Used to customize the label container Type: string\|array\|object	''
messages	Validation messages Type: array	[]
messagesChildProps	A set of props that are passed into the validation messages component Type: object	{}
messagesClass	Used to customize the validation messages component Type: string\|array\|object	''
name	The name of the input Type: string	''
rootClass	Additional class name for the root element. Can accept all of: String, Object, and Array, i.e. has the same api as Vue's built-in handling of the class attribute. Type: string\|object\|array	''
showMessages	Used to hide / show the validation messages Type: boolean Values: truefalse	true
v-model	Used to set the checked state of the checkable input Type: boolean	false
validationState	The validation state of the input Type: string	''
value	A provided value for the radio Type: string\|number	''

Events

Name	Description
focus	Native input focus event Type: FocusEvent
focusin	Native input focusin event Type: undefined
focusout	Native input focusout event Type: undefined
input	Native input event Type: String \| Number
update:modelValue	Event fired to sync the modelValue prop with the parent component Type: String \| Number

Preview

Usage #

Do

Don’t

Best Practices #

Variants and Examples #

Base Styles #

With Description Text #

With Validation States #

With Slotted Label #

With Slotted Description #

Classes #

Accessibility #

Vue API #