Documentation

You are viewing documentation for Vaadin 23. View latest documentation

Documentation

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" label="Economy"></vaadin-radio-button>
  <vaadin-radio-button value="business" label="Business"></vaadin-radio-button>
  <vaadin-radio-button value="firstClass" label="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 can’t be edited, but they are part of 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" label="In progress" checked></vaadin-radio-button>
  <vaadin-radio-button value="done" label="Done"></vaadin-radio-button>
  <vaadin-radio-button value="cancelled" label="Cancelled"></vaadin-radio-button>
</vaadin-radio-group>

Disabled

Disable a field to mark it as currently unavailable. The disabled state is used for fields that aren’t editable and don’t need to be readable. Disabled elements can’t be focused and may be inaccessible to assistive technologies such as 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 it’s currently unavailable.

Open in a
new tab
<vaadin-radio-group label="Status" disabled>
  <vaadin-radio-button value="inProgress" label="In progress" checked></vaadin-radio-button>
  <vaadin-radio-button value="done" label="Done"></vaadin-radio-button>
  <vaadin-radio-button value="cancelled" label="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" label="Pending" checked></vaadin-radio-button>
  <vaadin-radio-button value="submitted" label="Submitted"></vaadin-radio-button>
  <vaadin-radio-button value="confirmed" label="Confirmed"></vaadin-radio-button>
</vaadin-radio-group>

In cases where vertical space needs to be conserved, horizontal orientation can be used, but it’s recommended to have no more than three options:

Open in a
new tab
<vaadin-radio-group label="Status" theme="horizontal">
  <vaadin-radio-button value="pending" label="Pending" checked></vaadin-radio-button>
  <vaadin-radio-button value="submitted" label="Submitted"></vaadin-radio-button>
  <vaadin-radio-button value="confirmed" label="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 customized 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)}">
        <label slot="label">
          <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>
        </label>
      </vaadin-radio-button>
    `
  )}
</vaadin-radio-group>

Best Practices

Group Labels

It’s 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" label="Analyst" checked></vaadin-radio-button>
  <vaadin-radio-button value="administrator" label="Administrator"></vaadin-radio-button>
  <vaadin-radio-button value="engineer" label="Engineer"></vaadin-radio-button>
</vaadin-radio-group>

<vaadin-radio-group label="Department" theme="vertical">
  <vaadin-radio-button
    value="engineering"
    label="Engineering"
    checked
  ></vaadin-radio-button>
  <vaadin-radio-button value="humanResources" label="Human Resources"></vaadin-radio-button>
  <vaadin-radio-button value="marketing" label="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="${(event: RadioGroupValueChangedEvent) => {
      this.value = event.detail.value;
    }}"
  >
    ${this.items.map(
      (card) => html`
        <vaadin-radio-button .value="${String(card.id)}">
          <label slot="label">
            <vaadin-horizontal-layout theme="spacing">
              <img src="${card.pictureUrl}" alt="${card.name}" style="height: 1em;" />
              <span>${card.accountNumber}</span>
            </vaadin-horizontal-layout>
          </label>
        </vaadin-radio-button>
      `
    )}
    <vaadin-radio-button value="-1" label="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’s 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’s important that the user make 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" label="None" checked></vaadin-radio-button>
  <vaadin-radio-button value="daily" label="Daily"></vaadin-radio-button>
  <vaadin-radio-button value="weekly" label="Weekly"></vaadin-radio-button>
  <vaadin-radio-button value="monthly" label="Monthly"></vaadin-radio-button>
</vaadin-radio-group>

As an Alternative to a Checkbox

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

If the Checkbox doesn’t represent a simple yes/no choice, and its label can’t clearly communicate the meaning of its unchecked state, it’s better to use a Radio Button Group with two options:

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

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

Component Usage recommendations

Select

A drop-down 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

A scrollable list of options. Supports single and multi-select.

Checkbox

A corresponding component for multi-select options.

E1E617CE-F935-451D-885F-CEF94EC0E53A