> Markdown version of [Radio Button](https://vaadin.com/docs/v23/components/radio-button). Section index: [llms.txt](https://vaadin.com/docs/v23/components/llms.txt)

# Radio Button

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

**TypeScript** — `radio-button-basic.ts`

```html
<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>
```

**Java** — `RadioButtonBasic.java`

```java
RadioButtonGroup<String> radioGroup = new RadioButtonGroup<>();
radioGroup.addThemeVariants(RadioGroupVariant.LUMO_VERTICAL);
radioGroup.setLabel("Travel class");
radioGroup.setItems("Economy", "Business", "First Class");
add(radioGroup);
```

## <a id="common-input-field-features"></a>Common Input Field Features

Radio Button Group includes all shared input field features.

- [See shared input field features](https://vaadin.com/docs/v23/components/input-fields.md)

## <a id="states"></a>States

### <a id="read-only"></a>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.

**TypeScript** — `radio-button-readonly.ts`

```html
<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>
```

**Java** — `RadioButtonReadonly.java`

```java
RadioButtonGroup<String> radioGroup = new RadioButtonGroup<>();
radioGroup.setLabel("Status");
radioGroup.setItems("In progress", "Done", "Cancelled");
radioGroup.setValue("In progress");
radioGroup.setReadOnly(true);
add(radioGroup);
```

### <a id="disabled"></a>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.

**TypeScript** — `radio-button-disabled.ts`

```html
<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>
```

**Java** — `RadioButtonDisabled.java`

```java
RadioButtonGroup<String> radioGroup = new RadioButtonGroup<>();
radioGroup.setLabel("Status");
radioGroup.setItems("In progress", "Done", "Cancelled");
radioGroup.setValue("In progress");
radioGroup.setEnabled(false);
add(radioGroup);
```

## <a id="orientation"></a>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:

**TypeScript** — `radio-button-vertical.ts`

```html
<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>
```

**Java** — `RadioButtonVertical.java`

```java
RadioButtonGroup<String> radioGroup = new RadioButtonGroup<>();
radioGroup.addThemeVariants(RadioGroupVariant.LUMO_VERTICAL);
radioGroup.setLabel("Status");
radioGroup.setItems("Pending", "Submitted", "Confirmed");
radioGroup.setValue("Pending");
add(radioGroup);
```

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:

**TypeScript** — `radio-button-horizontal.ts`

```html
<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>
```

**Java** — `RadioButtonHorizontal.java`

```java
RadioButtonGroup<String> radioGroup = new RadioButtonGroup<>();
radioGroup.setLabel("Status");
radioGroup.setItems("Pending", "Submitted", "Confirmed");
radioGroup.setValue("Pending");
add(radioGroup);
```

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

## <a id="custom-item-presentation"></a>Custom Item Presentation

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

**TypeScript** — `radio-button-presentation.ts`

```typescript
<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>
```

**Java** — `RadioButtonPresentation.java`

```java
RadioButtonGroup<Card> radioGroup = new RadioButtonGroup<>();
radioGroup.addThemeVariants(RadioGroupVariant.LUMO_VERTICAL);
radioGroup.setLabel("Payment method");

List<Card> cards = DataService.getCards();
radioGroup.setItems(cards);
radioGroup.setValue(cards.get(0));
radioGroup.setRenderer(new ComponentRenderer<>(card -> {
    Image logo = new Image(card.getPictureUrl(), card.getName());
    logo.setHeight("1em");
    Span number = new Span(new Text(card.getAccountNumber()));
    Text expiryDate = new Text("Expiry date:" + card.getExpiryDate());

    return new Div(new HorizontalLayout(logo, number),
            new Div(expiryDate));
}));

add(radioGroup);
```

**Java** — `Card.java`

```java
package com.vaadin.demo.domain;


// tag::snippet[]
public class Card {

    private String name;

    private String accountNumber;

    private String pictureUrl;

    private String expiryDate;

    private String cvv;

    private Integer id;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getAccountNumber() {
        return accountNumber;
    }

    public void setAccountNumber(String accountNumber) {
        this.accountNumber = accountNumber;
    }

    public String getPictureUrl() {
        return pictureUrl;
    }

    public void setPictureUrl(String pictureUrl) {
        this.pictureUrl = pictureUrl;
    }

    public String getExpiryDate() {
        return expiryDate;
    }

    public void setExpiryDate(String expiryDate) {
        this.expiryDate = expiryDate;
    }

    public String getCvv() {
        return cvv;
    }

    public void setCvv(String cvv) {
        this.cvv = cvv;
    }

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    @Override
    public int hashCode() {
        return id;
    }

    @Override
    public boolean equals(Object obj) {
        if (this == obj) {
            return true;
        }
        if (!(obj instanceof Card)) {
            return false;
        }
        Card other = (Card) obj;
        return id == other.id;
    }
}
// end::snippet[]
```

**Java** — `DataService.java`

```java
package com.vaadin.demo.domain;

import java.io.InputStream;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

import com.fasterxml.jackson.databind.ObjectMapper;

import org.springframework.core.io.ClassPathResource;

public class DataService {

    public static <T> T getItems(Class<T> clazz, String dataFileName) {
        ObjectMapper mapper = new ObjectMapper();
        try {
            InputStream stream = new ClassPathResource("data/" + dataFileName)
                    .getInputStream();
            return mapper.readValue(stream, clazz);
        } catch (Exception e) {
            e.printStackTrace();
        }
        return null;
    }

    public static List<Person> getPeople() {
        List<Person> people = Arrays
                .asList(getItems(Person[].class, "people.json"));
        List<String> peopleImages = Arrays
                .asList(getItems(String[].class, "peopleImages.json"));
        for (int index = 0; index < people.size(); index++) {
            String pictureUrl = peopleImages.get(index % peopleImages.size());
            people.get(index).setPictureUrl(pictureUrl);
        }
        return people;
    }

    public static List<Person> getPeople(int count) {
        return getPeople().subList(0, count);
    }

    public static List<Person> getPeople(int count, Integer managerId) {
        List<Person> people = getPeople(managerId);
        return people.subList(0, count);
    }

    public static List<String> getProfessions() {
        List<Person> people = Arrays
                .asList(getItems(Person[].class, "people.json"));
        ArrayList<String> professions = new ArrayList<>();
        for (Person person : people) {
            String profession = person.getProfession();
            if (!professions.contains(profession)) {
                professions.add(profession);
            }
        }
        return professions;
    }

    /**
     * Get employees for a given manager.
     */
    public static List<Person> getPeople(Integer managerId) {
        List<Person> people = new ArrayList<>(getPeople());
        people.removeIf(person -> person.getManagerId() == null
                || !person.getManagerId().equals(managerId));
        return people;
    }

    /**
     * Get all managers.
     */
    public static List<Person> getManagers() {
        List<Person> people = new ArrayList<>(getPeople());
        people.removeIf(person -> !person.isManager());
        return people;
    }

    public static Templates getTemplates() {
        return getItems(Templates.class, "templates.json");
    }

    public static List<Card> getCards() {
        return Arrays.asList(getItems(Card[].class, "cards.json"));
    }

    public static List<Country> getCountries() {
        return Arrays.asList(getItems(Country[].class, "countries.json"));
    }

    public static List<UserPermissions> getUserPermissions() {
        return Arrays
                .asList(getItems(UserPermissions[].class, "permissions.json"));
    }

    public static List<Report> getReports() {
        return Arrays.asList(getItems(Report[].class, "reports.json"));
    }
}
```

## <a id="best-practices"></a>Best Practices

### <a id="group-labels"></a>Group Labels

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

**TypeScript** — `radio-button-group-labels.ts`

```html
<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>
```

**Java** — `RadioButtonGroupLabels.java`

```java
RadioButtonGroup<String> jobTitleGroup = new RadioButtonGroup<>();
jobTitleGroup.addThemeVariants(RadioGroupVariant.LUMO_VERTICAL);
jobTitleGroup.setLabel("Job title");
jobTitleGroup.setItems("Analyst", "Administrator", "Engineer");
jobTitleGroup.setValue("Analyst");
add(jobTitleGroup);

RadioButtonGroup<String> departmentGroup = new RadioButtonGroup<>();
departmentGroup.addThemeVariants(RadioGroupVariant.LUMO_VERTICAL);
departmentGroup.setLabel("Department");
departmentGroup.setItems("Engineering", "Human Resources", "Marketing");
departmentGroup.setValue("Engineering");
add(departmentGroup);
```

### <a id="custom-option"></a>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.

**TypeScript** — `radio-button-custom-option.ts`

```typescript
<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>
```

**Java** — `RadioButtonCustomOption.java`

```java
RadioButtonGroup<Card> radioGroup = new RadioButtonGroup<>();
radioGroup.addThemeVariants(RadioGroupVariant.LUMO_VERTICAL);
radioGroup.setLabel("Payment method");

List<Card> cards = new ArrayList<>(DataService.getCards());
Card other = new Card();
other.setId(-1);
cards.add(other);
radioGroup.setItems(cards);
radioGroup.setValue(cards.get(0));

radioGroup.setRenderer(new ComponentRenderer<>(card -> {
    if (other.equals(card)) {
        return new Text("Other");
    } else {
        Image logo = new Image(card.getPictureUrl(), card.getName());
        logo.setHeight("1em");
        Span number = new Span(new Text(card.getAccountNumber()));
        return new HorizontalLayout(logo, number);
    }
}));

TextField textField = new TextField("Card number");
textField.setVisible(false);
radioGroup.addValueChangeListener(
        e -> textField.setVisible(other.equals(e.getValue())));

add(radioGroup, textField);
```

### <a id="default-value-and-blank-option"></a>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:

**TypeScript** — `radio-button-default-value.ts`

```typescript
<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>
```

### <a id="as-an-alternative-to-a-checkbox"></a>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:

**TypeScript** — `radio-button-checkbox-alternative.ts`

```typescript
<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.

## <a id="related-components"></a>Related Components

| Component                                                        | Usage recommendations                                                                                                                  |
| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| [Select](https://vaadin.com/docs/v23/components/select.md)       | 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](https://vaadin.com/docs/v23/components/combo-box.md) | A filterable, lazy-loading alternative to Select, recommended for ten or more items.                                                   |
| [List Box](https://vaadin.com/docs/v23/components/list-box.md)   | A scrollable list of options. Supports single and multi-select.                                                                        |
| [Checkbox](https://vaadin.com/docs/v23/components/checkbox.md)   | A corresponding component for multi-select options.                                                                                    |

`E1E617CE-F935-451D-885F-CEF94EC0E53A`
