Checkbox
Checkbox is an input field representing a binary choice. Checkbox Group is a group of related binary choices.
new tab
Checkbox checkbox = new Checkbox();
checkbox.setLabel("I accept the terms and conditions");
add(checkbox);
new tab
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);
Use Checkbox Group to group related items. Individual checkboxes should be used for options that are not 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 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.
new tab
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);
Note
|
Read-only state
Checkbox does not 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.
new tab
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);
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:
new tab
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);
In cases where vertical space needs to be conserved, horizontal orientation can be used, but no more than 3 options are recommended:
new tab
CheckboxGroup<String> checkboxGroup = new CheckboxGroup<>();
checkboxGroup.setLabel("Permissions");
checkboxGroup.setItems("Read", "Edit", "Delete");
add(checkboxGroup);
Best Practices
Labeling
Aim for short and descriptive labels using positive wording. Avoid negations.
new tab
import { html, LitElement, customElement } from 'lit-element';
import '@vaadin/vaadin-checkbox/vaadin-checkbox';
import { applyTheme } from 'Frontend/generated/theme';
// tag::snippet[]
@customElement('checkbox-labeling')
export class Example extends LitElement {
protected createRenderRoot() {
const root = super.createRenderRoot();
// Apply custom theme (only supported if your app uses one)
applyTheme(root);
return root;
}
render() {
return html`
<vaadin-checkbox>Yes, I agree</vaadin-checkbox>
`;
}
}
// end::snippet[]
It is important to provide labels for Checkbox Groups to clearly distinguish adjacent groups.
new tab
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);
Related Components
Component | Usage recommendations |
---|---|
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. | |
A filterable, lazy loading alternative to Select, recommended for ten or more items. | |
Scrollable list of options. Supports single and multi-select. | |
Corresponding component for mutually exclusive options, or “single-select”. |
8B864673-06F1-45B7-A039-5087706B427B