Radio

Storybook Source

Form control for choosing one option from a set.

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

With Slotted Label

With Slotted Description

Label size

Use the label-size prop to override the default label size.

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 

import { DtRadio } from '@dialpad/dialtone-vue';

Slots

Name
Type
default

slot for Radio Label

description

slot for Radio Description

Props

Name
Default
Type
description
''
string

Describes the input

descriptionChildProps
{}
object

A set of props that are passed into the description container

descriptionClass
''
string|array|object

Used to customize the description container

disabled
false
boolean

Disables the input

indeterminate
false
boolean

Indeterminate State, toggling indeterminate checkbox will uncheck

inputClass
''
string|array|object

Used to customize the input element

label
''
string

A provided label for the input

labelChildProps
{}
object

A set of props that are passed into the label container

labelClass
''
string|array|object

Used to customize the label container

labelSize
null
"100" | "200" | "300" | "400"

Overrides the label text size.

labelStrength
null
"bold" | "semibold" | "medium" | "normal"

Overrides the label font weight.

messages
[]
array

Validation messages

messagesChildProps
{}
object

A set of props that are passed into the validation messages component

messagesClass
''
string|array|object

Used to customize the validation messages component

name
''
string

The name of the input

showLabel
true
"true" | "false"

Determines visibility of radio label.

showMessages
true
"true" | "false"

Used to hide / show the validation messages

v-model
false
boolean

Used to set the checked state of the checkable input

validationState
''
string

The validation state of the input

value
''
string|number

A provided value for the radio

Events

Name
Type
focus
FocusEvent

Native input focus event

focusin
undefined

Native input focusin event

focusout
undefined

Native input focusout event

update:modelValue
String | Number

Event fired to sync the modelValue prop with the parent component

Classes

Class
Applies to
Description

Radio documentation last updated Friday, September 4, 2026

fix/popover-modal-zindex-scope