Checkbox

Common Input Field Features
States
Orientation
Best Practices
Related Components

Checkbox is an input field representing a binary choice. Checkbox Group is a group of related binary choices.

Source code

checkbox-basic.ts
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/checkbox';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('checkbox-basic')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-checkbox label="I accept the terms and conditions"></vaadin-checkbox>
      <!-- end::snippet[] -->
    `;
  }
}
CheckboxBasic.javapackage com.vaadin.demo.component.checkbox;

import com.vaadin.flow.component.checkbox.Checkbox;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;

@Route("checkbox-basic")
public class CheckboxBasic extends Div {

    public CheckboxBasic() {
        // tag::snippet[]
        Checkbox checkbox = new Checkbox();
        checkbox.setLabel("I accept the terms and conditions");

        add(checkbox);
        // end::snippet[]
    }

}

Open in a
new tab

Source code

checkbox-group-basic.ts
import { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import '@vaadin/checkbox';
import '@vaadin/checkbox-group';
import type { CheckboxGroupValueChangedEvent } from '@vaadin/checkbox-group';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('checkbox-group-basic')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @state()
  private value = ['0', '2'];

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-checkbox-group
        label="Export data"
        .value="${this.value}"
        @value-changed="${(event: CheckboxGroupValueChangedEvent) => {
          this.value = event.detail.value;
        }}"
        theme="vertical"
      >
        <vaadin-checkbox value="0" label="Order ID"></vaadin-checkbox>
        <vaadin-checkbox value="1" label="Product name"></vaadin-checkbox>
        <vaadin-checkbox value="2" label="Customer"></vaadin-checkbox>
        <vaadin-checkbox value="3" label="Status"></vaadin-checkbox>
      </vaadin-checkbox-group>
      <!-- end::snippet[] -->
    `;
  }
}
CheckboxGroupBasic.javapackage com.vaadin.demo.component.checkbox;

import com.vaadin.flow.component.checkbox.CheckboxGroup;
import com.vaadin.flow.component.checkbox.CheckboxGroupVariant;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;


@Route("checkbox-group-basic")
public class CheckboxGroupBasic extends Div {

    public CheckboxGroupBasic() {
        // tag::snippet[]
        CheckboxGroup<String> checkboxGroup = new CheckboxGroup<>();
        checkboxGroup.setLabel("Export data");
        checkboxGroup.setItems("Order ID", "Product name", "Customer",
                "Status");
        checkboxGroup.select("Order ID", "Customer");
        checkboxGroup.addThemeVariants(CheckboxGroupVariant.LUMO_VERTICAL);
        add(checkboxGroup);
        // end::snippet[]
    }

}

Use Checkbox Group to group related items. Individual checkboxes should be used for options that aren’t related to each other in any way.

Common Input Field Features

Checkbox Group includes all shared input field features.

See shared input field features

States

Disabled

Disable a field to mark it as currently unavailable. 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 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

Source code

checkbox-disabled.ts
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/checkbox';
import '@vaadin/checkbox-group';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('checkbox-disabled')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-checkbox-group label="Departments" theme="vertical" disabled>
        <vaadin-checkbox value="engineering" label="Engineering"></vaadin-checkbox>
        <vaadin-checkbox value="human-resources" label="Human Resources"></vaadin-checkbox>
        <vaadin-checkbox value="marketing" label="Marketing"></vaadin-checkbox>
        <vaadin-checkbox value="operations" label="Operations"></vaadin-checkbox>
        <vaadin-checkbox value="sales" label="Sales"></vaadin-checkbox>
      </vaadin-checkbox-group>
      <!-- end::snippet[] -->
    `;
  }
}
CheckboxDisabled.javapackage com.vaadin.demo.component.checkbox;

import com.vaadin.flow.component.checkbox.CheckboxGroup;
import com.vaadin.flow.component.checkbox.CheckboxGroupVariant;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;

@Route("checkbox-disabled")
public class CheckboxDisabled extends Div {

    public CheckboxDisabled() {
        // tag::snippet[]
        CheckboxGroup<String> disabledCheckGroup = new CheckboxGroup<>();
        disabledCheckGroup.setLabel("Departments");
        disabledCheckGroup.setItems("Engineering", "Human Resources",
                "Marketing", "Operations", "Sales");
        disabledCheckGroup.addThemeVariants(CheckboxGroupVariant.LUMO_VERTICAL);
        disabledCheckGroup.setEnabled(false);
        add(disabledCheckGroup);
        // end::snippet[]
    }

}

Note	Read-only state Checkbox doesn’t support read-only state.

Indeterminate

The indeterminate state can be used for a parent checkbox to show that there is a mix of checked and unchecked child items in a list, and to change the state of all child items at once.

Open in a
new tab

Source code

checkbox-indeterminate.ts
import { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import '@vaadin/checkbox';
import '@vaadin/checkbox-group';
import '@vaadin/vertical-layout';
import type { CheckboxGroupValueChangedEvent } from '@vaadin/checkbox-group';
import { getPeople } from 'Frontend/demo/domain/DataService';
import type Person from 'Frontend/generated/com/vaadin/demo/domain/Person';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('checkbox-indeterminate')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @state()
  private items: Person[] = [];

  @state()
  private selectedIds: string[] = [];

  protected override async firstUpdated() {
    const { people } = await getPeople({ count: 3 });
    this.items = people;
    this.selectedIds = [String(this.items[0].id), String(this.items[2].id)];
  }

  protected override render() {
    const { items, selectedIds } = this;

    return html`
      <vaadin-vertical-layout theme="spacing">
        <!-- tag::snippet[] -->
        <vaadin-checkbox
          label="Notify users"
          .checked="${selectedIds.length === items.length}"
          .indeterminate="${selectedIds.length > 0 && selectedIds.length < items.length}"
          @change="${(e: Event) => {
            this.selectedIds = (e.target as HTMLInputElement).checked
              ? this.items.map((person) => String(person.id))
              : [];
          }}"
        ></vaadin-checkbox>

        <vaadin-checkbox-group
          label="Users to notify"
          theme="vertical"
          .value="${this.selectedIds}"
          @value-changed="${(event: CheckboxGroupValueChangedEvent) => {
            this.selectedIds = event.detail.value;
          }}"
        >
          ${items.map(
            (person) => html`
              <vaadin-checkbox
                .value="${String(person.id)}"
                label="${person.firstName} ${person.lastName}"
              ></vaadin-checkbox>
            `
          )}
        </vaadin-checkbox-group>
        <!-- end::snippet[] -->
      </vaadin-vertical-layout>
    `;
  }
}
CheckboxIndeterminate.javapackage com.vaadin.demo.component.checkbox;

import com.vaadin.flow.component.checkbox.Checkbox;
import com.vaadin.flow.component.checkbox.CheckboxGroup;
import com.vaadin.flow.component.checkbox.CheckboxGroupVariant;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.router.Route;

import java.util.HashSet;
import java.util.List;

import com.vaadin.demo.domain.DataService;
import com.vaadin.demo.domain.Person;

@Route("checkbox-indeterminate")
public class CheckboxIndeterminate extends VerticalLayout {

    private List<Person> items = DataService.getPeople(3);

    public CheckboxIndeterminate() {
        setPadding(false);

        // tag::snippet[]
        Checkbox checkbox = new Checkbox("Notify users");

        CheckboxGroup<Person> checkboxGroup = new CheckboxGroup<>();
        checkboxGroup.setLabel("Users to notify");
        checkboxGroup.setItemLabelGenerator(
                person -> person.getFirstName() + " " + person.getLastName());
        checkboxGroup.setItems(items);
        checkboxGroup.addThemeVariants(CheckboxGroupVariant.LUMO_VERTICAL);
        checkboxGroup.addValueChangeListener(event -> {
            if (event.getValue().size() == items.size()) {
                checkbox.setValue(true);
                checkbox.setIndeterminate(false);
            } else if (event.getValue().size() == 0) {
                checkbox.setValue(false);
                checkbox.setIndeterminate(false);
            } else {
                checkbox.setIndeterminate(true);
            }
        });
        checkbox.addValueChangeListener(event -> {
            if (checkbox.getValue()) {
                checkboxGroup.setValue(new HashSet<>(items));
            } else {
                checkboxGroup.deselectAll();
            }
        });
        checkboxGroup.select(items.get(0), items.get(2));
        add(checkbox, checkboxGroup);
        // end::snippet[]
    }

}

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

Source code

checkbox-vertical.ts
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/checkbox';
import '@vaadin/checkbox-group';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('checkbox-vertical')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-checkbox-group label="Working days" theme="vertical">
        <vaadin-checkbox value="mon" label="Monday"></vaadin-checkbox>
        <vaadin-checkbox value="tue" label="Tuesday"></vaadin-checkbox>
        <vaadin-checkbox value="wed" label="Wednesday"></vaadin-checkbox>
        <vaadin-checkbox value="thu" label="Thursday"></vaadin-checkbox>
        <vaadin-checkbox value="fri" label="Friday"></vaadin-checkbox>
        <vaadin-checkbox value="sat" label="Saturday"></vaadin-checkbox>
        <vaadin-checkbox value="sun" label="Sunday"></vaadin-checkbox>
      </vaadin-checkbox-group>
      <!-- end::snippet[] -->
    `;
  }
}
CheckboxVertical.javapackage com.vaadin.demo.component.checkbox;

import com.vaadin.flow.component.checkbox.CheckboxGroup;
import com.vaadin.flow.component.checkbox.CheckboxGroupVariant;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;

@Route("checkbox-vertical")
public class CheckboxVertical extends Div {

    public CheckboxVertical() {
        // tag::snippet[]
        CheckboxGroup<String> checkboxGroup = new CheckboxGroup<>();
        checkboxGroup.setLabel("Working days");
        checkboxGroup.setItems("Monday", "Tuesday", "Wednesday", "Thursday",
                "Friday", "Saturday", "Sunday");
        checkboxGroup.addThemeVariants(CheckboxGroupVariant.LUMO_VERTICAL);
        add(checkboxGroup);
        // end::snippet[]
    }

}

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

Source code

checkbox-horizontal.ts
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/checkbox';
import '@vaadin/checkbox-group';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('checkbox-horizontal')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-checkbox-group label="Permissions">
        <vaadin-checkbox value="read" label="Read"></vaadin-checkbox>
        <vaadin-checkbox value="edit" label="Edit"></vaadin-checkbox>
        <vaadin-checkbox value="delete" label="Delete"></vaadin-checkbox>
      </vaadin-checkbox-group>
      <!-- end::snippet[] -->
    `;
  }
}
CheckboxHorizontal.javapackage com.vaadin.demo.component.checkbox;

import com.vaadin.flow.component.checkbox.CheckboxGroup;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;

@Route("checkbox-horizontal")
public class CheckboxHorizontal extends Div {

    public CheckboxHorizontal() {
        // tag::snippet[]
        CheckboxGroup<String> checkboxGroup = new CheckboxGroup<>();
        checkboxGroup.setLabel("Permissions");
        checkboxGroup.setItems("Read", "Edit", "Delete");
        add(checkboxGroup);
        // end::snippet[]
    }

}

Best Practices

Labeling

Aim for short and descriptive labels using positive wording. Avoid negations.

Open in a
new tab

Source code

checkbox-labeling.ts
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/checkbox';
import { applyTheme } from 'Frontend/generated/theme';

// tag::snippet[]
@customElement('checkbox-labeling')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`<vaadin-checkbox label="Yes, I agree"></vaadin-checkbox>`;
  }
}
// end::snippet[]

It’s important to provide labels for Checkbox Groups to clearly distinguish adjacent groups.

Open in a
new tab

Source code

checkbox-adjacent-groups.ts
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import '@vaadin/checkbox';
import '@vaadin/checkbox-group';
import '@vaadin/vertical-layout';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('checkbox-adjacent-groups')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-vertical-layout>
        <vaadin-checkbox-group label="Manufacturer" theme="vertical">
          <vaadin-checkbox value="0" label="Akuchi"></vaadin-checkbox>
          <vaadin-checkbox value="1" label="Broek"></vaadin-checkbox>
          <vaadin-checkbox value="2" label="Wulf"></vaadin-checkbox>
        </vaadin-checkbox-group>

        <vaadin-checkbox-group label="Status" theme="vertical">
          <vaadin-checkbox value="0" label="In progress"></vaadin-checkbox>
          <vaadin-checkbox value="1" label="Done"></vaadin-checkbox>
          <vaadin-checkbox value="2" label="Cancelled"></vaadin-checkbox>
        </vaadin-checkbox-group>
      </vaadin-vertical-layout>
      <!-- end::snippet[] -->
    `;
  }
}
CheckboxAdjacentGroups.javapackage com.vaadin.demo.component.checkbox;

import com.vaadin.flow.component.checkbox.CheckboxGroup;
import com.vaadin.flow.component.checkbox.CheckboxGroupVariant;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.router.Route;

@Route("checkbox-adjacent-groups")
public class CheckboxAdjacentGroups extends VerticalLayout {

    public CheckboxAdjacentGroups() {
        setPadding(false);
        setSpacing(false);

        // tag::snippet[]
        CheckboxGroup<String> manufacturer = new CheckboxGroup<>();
        manufacturer.setLabel("Manufacturer");
        manufacturer.setItems("Akuchi", "Broek", "Wulf");
        manufacturer.addThemeVariants(CheckboxGroupVariant.LUMO_VERTICAL);

        CheckboxGroup<String> status = new CheckboxGroup<>();
        status.setLabel("Status");
        status.setItems("In progress", "Done", "Cancelled");
        status.addThemeVariants(CheckboxGroupVariant.LUMO_VERTICAL);

        add(manufacturer, status);
        // end::snippet[]
    }

}

Component	Usage recommendations
Select	A field for selecting an item from a list of options which are presented in an overlay. 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.
Radio Button Group	Corresponding component for mutually exclusive options, or “single-select”.

Component

Usage recommendations

Select

A field for selecting an item from a list of options which are presented in an overlay. 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.

Radio Button Group

Corresponding component for mutually exclusive options, or “single-select”.

F86F2BE5-1BDA-4E79-BD9E-6CE12742450B

Documentation

Documentation

Checkbox

Common Input Field Features

States

Disabled

Indeterminate

Orientation

Best Practices

Labeling

Documentation

Common Input Field Features

States

Disabled

Indeterminate

Orientation

Best Practices

Labeling

Related Components