Documentation

Documentation

Checkbox

Source: TypeScript / Java
Checkbox is an input field representing a binary choice.

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

Open in a
new tab
<vaadin-checkbox label="I accept the terms and conditions"></vaadin-checkbox>
Open in a
new tab
<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>

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

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

Orientation

The component’s default orientation is horizontal. However, 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-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>

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

Open in a
new tab
<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>

Basic Features

The following features, common to most input field components, are supported:

Label

The label is used to identify the input field. It supports plain-text content, and its length is limited to the width of the field. Helpers and Tooltips can be used to provide additional information that doesn’t fit into the label.

Visible labels are strongly recommended for all input fields. In cases where the built-in label cannot be used, an external element can be associated as the field’s label through the aria-labelledby attribute. Fields without any visible label should include an invisible label for assistive technologies with the aria-label attribute.

Helper

Helpers are used to provide additional information that the user may need to enter in the field, such as format requirements or explanations of the field’s purpose below the field.

A style variant is available for rendering the helper above the field.

In addition to plain text, helpers can contain components and HTML elements. However, complex and interactive content is likely to have accessibility issues.

Tooltip

Tooltips are small text pop-ups displayed on hover, and on keyboard-focus. They can be used to provide additional information about a field. This can be useful in situations where an always visible Helper is not appropriate. Helpers are generally recommended in favor of tooltips, though, as they provide much better discoverability and mobile support. See the Tooltip documentation for more information.

External & Invisible Labels (ARIA)

Visible labels are strongly recommended for all input fields. In situations where the built-in label cannot be used, an external element can be associated as the field’s label through its element id. Fields without any visible label should be provided an invisible label for assistive technologies like screen readers.

<!-- Associates external element as label: -->
<label id="external-label">This is the label</label>
<vaadin-checkbox accessible-name-ref="external-label">...

<!-- Invisible label for screen readers: -->
<vaadin-checkbox accessible-name="This is the label">...
Open in a
new tab
<vaadin-checkbox-group label="Label" helper-text="Helper text">
  <vaadin-tooltip slot="tooltip" text="Tooltip text"></vaadin-tooltip>
  <vaadin-checkbox value="1" label="Item 1"></vaadin-checkbox>
  <vaadin-checkbox value="2" label="Item 2"></vaadin-checkbox>
  <vaadin-checkbox value="3" label="Item 3"></vaadin-checkbox>
</vaadin-checkbox-group>

Style Variants

The following style variants can be applied:

Helper Above Field

The helper can be rendered above the field, and below the label.

Borders

Borders can be applied to the field surface by providing a value (e.g., 1px) to the --vaadin-input-field-border-width CSS property. This can be applied globally to all input fields using the html selector, or to individual component instances. Borders are required to achieve WCAG 2.1 level AA conformant color contrast with the default Lumo styling of fields.

You can override the default border color with the --vaadin-input-field-border-color property.

Open in a
new tab
<vaadin-checkbox-group
  theme="helper-above-field"
  label="Label"
  helper-text="Helper text"
  style="--vaadin-input-field-border-width: 1px;"
>
</vaadin-checkbox-group>

Best Practices

Labeling

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

Open in a
new tab
@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>`;
  }
}

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

Open in a
new tab
<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>
Component Usage Recommendation

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