My Design System

My Design System

Radio Button

Source: TypeScript / Java

Radio Button Group allows the user to select exactly one value from a list of related but mutually exclusive options.

Open in a
new tab
<vaadin-radio-group label="Travel class" theme="vertical">
  <vaadin-radio-button value="economy">Economy</vaadin-radio-button>
  <vaadin-radio-button value="business">Business</vaadin-radio-button>
  <vaadin-radio-button value="firstClass">First Class</vaadin-radio-button>
</vaadin-radio-group>

Common Input Field Features

Radio Button Group includes all shared input field features.

States

Read-Only

Use read-only when content needs to be accessible but not editable. Read-only elements cannot be edited, but they do participate in the tabbing order and can thus receive focus. The contents of a read-only input can be selected and copied.

Open in a
new tab
<vaadin-radio-group label="Status" readonly>
  <vaadin-radio-button value="inProgress" checked>In progress</vaadin-radio-button>
  <vaadin-radio-button value="done">Done</vaadin-radio-button>
  <vaadin-radio-button value="cancelled">Cancelled</vaadin-radio-button>
</vaadin-radio-group>

Disabled

Disable a field to mark it as currently unavailable. Disabled state is used for fields that are not editable and do not need to be readable. Disabled elements cannot be focused and may be inaccessible to assistive technologies like screen readers.

Disabling can be preferable to hiding an element to prevent changes in layout when the element’s visibility changes, and to make users aware of its existence even when currently unavailable.

Open in a
new tab
<vaadin-radio-group label="Status" disabled>
  <vaadin-radio-button value="inProgress" checked>In progress</vaadin-radio-button>
  <vaadin-radio-button value="done">Done</vaadin-radio-button>
  <vaadin-radio-button value="cancelled">Cancelled</vaadin-radio-button>
</vaadin-radio-group>

Orientation

The component’s default orientation is horizontal but vertical orientation is recommended whenever possible as it’s easier for the user to scan a vertical list of options:

Open in a
new tab
<vaadin-radio-group label="Status" theme="vertical">
  <vaadin-radio-button value="pending" checked>Pending</vaadin-radio-button>
  <vaadin-radio-button value="submitted">Submitted</vaadin-radio-button>
  <vaadin-radio-button value="confirmed">Confirmed</vaadin-radio-button>
</vaadin-radio-group>

In cases where vertical space needs to be conserved, horizontal orientation can be used, but no more than 3 options are recommended:

Open in a
new tab
<vaadin-radio-group label="Status" theme="horizontal">
  <vaadin-radio-button value="pending" checked>Pending</vaadin-radio-button>
  <vaadin-radio-button value="submitted">Submitted</vaadin-radio-button>
  <vaadin-radio-button value="confirmed">Confirmed</vaadin-radio-button>
</vaadin-radio-group>

In cases where more options need to be provided, the Select component can be used instead.

Custom Item Presentation

Items can be customised to include more than a single line of text:

Open in a
new tab
<vaadin-radio-group label="Payment method" theme="vertical" .value="${this.value}">
  ${this.items.map(
    (card) => html`
      <vaadin-radio-button .value="${String(card.id)}">
        <div>
          <vaadin-horizontal-layout theme="spacing">
            <img src="${card.pictureUrl}" alt="${card.name}" style="height: 1em;" />
            <span>${card.accountNumber}</span>
          </vaadin-horizontal-layout>
          <div>Expiry date:${card.expiryDate}</div>
        </div>
      </vaadin-radio-button>
    `
  )}
</vaadin-radio-group>

Best Practices

Group Labels

It is important to provide labels for Radio Button Groups to clearly distinguish them from one another, especially with multiple adjacent groups.

Open in a
new tab
<vaadin-radio-group label="Job title" theme="vertical">
  <vaadin-radio-button value="analyst" checked>Analyst</vaadin-radio-button>
  <vaadin-radio-button value="administrator">Administrator</vaadin-radio-button>
  <vaadin-radio-button value="engineer">Engineer</vaadin-radio-button>
</vaadin-radio-group>

<vaadin-radio-group label="Department" theme="vertical">
  <vaadin-radio-button value="engineering" checked>Engineering</vaadin-radio-button>
  <vaadin-radio-button value="humanResources">Human Resources</vaadin-radio-button>
  <vaadin-radio-button value="marketing">Marketing</vaadin-radio-button>
</vaadin-radio-group>

Custom Option

To enable the user to enter a custom option instead of picking one from the list, use an “Other” radio button at the bottom of the list with an associated Text Field for entry. The field should be hidden or disabled until the “Other” option is selected.

Open in a
new tab
<vaadin-vertical-layout>
  <vaadin-radio-group
    label="Payment method"
    theme="vertical"
    .value="${this.value}"
    @value-changed="${(e: CustomEvent) => (this.value = e.detail.value)}"
  >
    ${this.items.map(
      (card) => html`
        <vaadin-radio-button .value="${String(card.id)}">
          <vaadin-horizontal-layout theme="spacing">
            <img src="${card.pictureUrl}" alt="${card.name}" style="height: 1em;" />
            <span>${card.accountNumber}</span>
          </vaadin-horizontal-layout>
        </vaadin-radio-button>
      `
    )}
    <vaadin-radio-button value="-1">Other</vaadin-radio-button>
  </vaadin-radio-group>

  <vaadin-text-field label="Card number" .hidden="${this.value !== '-1'}"></vaadin-text-field>
</vaadin-vertical-layout>

Default Value and Blank Option

It is generally recommended to set the most common option as the default value for Radio Button Groups. Place the default option at the top of the list.

In cases where it is important that the user makes a conscious choice, the Radio Button Group should be blank by default.

In situations where the user isn’t required to select a value, use a “blank” option:

Open in a
new tab
<vaadin-radio-group label="Repeat" theme="vertical">
  <vaadin-radio-button value="none" checked>None</vaadin-radio-button>
  <vaadin-radio-button value="daily">Daily</vaadin-radio-button>
  <vaadin-radio-button value="weekly">Weekly</vaadin-radio-button>
  <vaadin-radio-button value="monthly">Monthly</vaadin-radio-button>
</vaadin-radio-group>

As Alternative to a Checkbox

Two Radio Buttons can sometimes be a better alternative to a single Checkbox.

If the Checkbox does not represent a simple yes/no choice, and its label cannot clearly communicate the meaning of its unchecked state, it is better to use a Radio Button Group with two options:

Open in a
new tab
<vaadin-checkbox checked>Reply All by default (unchecked state not clear)</vaadin-checkbox>
<vaadin-radio-group label="Default reply behavior">
  <vaadin-radio-button checked>Reply</vaadin-radio-button>
  <vaadin-radio-button>Reply to all</vaadin-radio-button>
</vaadin-radio-group>

In a Horizontal Layout, Radio Button Groups also align more easily with other input fields than a single checkbox.

ComponentUsage recommendations

Select

A dropdown field for selecting an item from a list of options. Recommended when there is insufficient space for a Radio Button Group.

Combo Box

A filterable, lazy loading alternative to Select, recommended for ten or more items.

List Box

Scrollable list of options. Supports single and multi-select.

Checkbox

Corresponding component for multi-select options.