Use for selecting multiple options from a set of checkboxes.
The q2-checkbox-group element has one or more properties that support text localization. Those properties are indicated by the localizable badge in the description.
disabledDetermines if all checkboxes in the group are put into a disabled state.
hasErrorhas-errorDetermines if the component should display in an errant state.
hideLabelhide-labelHide's the group's <label> element from view.
Only use when a visible label is impractical.
labelThe label that displays above all the checkboxes.
optionalDetermines if the component is marked as optional.
readonlyDetermines if all the checkboxes are marked as readonly.
valueCan be used to get and set the checked status of each <q2-checkbox> element contained within the group.
Example:
element.value = {
'checkbox-value-1': true,
'checkbox-value-2': false,
'checkbox-value-3': true,
};
// Also accepts partial values
element.value = {
'checkbox-value-2': false,
}The q2-checkbox-group element exposes events that can be used to send and receive data from the component based on user interaction.
Emitted when the checkbox selection changes.
anyThe q2-checkbox-group element exposes methods that can be used to perform various actions on the component.
Emulates clicking the <q2-checkbox> option(s) with the provided value.
setValue(values: string | string[]) => Promise<void>The q2-checkbox-group element has one slot that can be used to insert custom content into the component.
An optional slot to display a custom label.
A common pattern is to use a "Select All" checkbox that controls the checked state of all checkboxes in a group. This leverages the indeterminate state on q2-checkbox to indicate when some, but not all, options are selected.
Select-all checkbox state reflects the group:
Clicking the select-all checkbox:
This follows the W3C Mixed-State Checkbox pattern.
Place the select-all q2-checkbox outside the q2-checkbox-group so the group's tctChange event only reflects individual option states. Use the group's value property to programmatically check or uncheck all options at once.
<q2-checkbox id="select-all" label="Select All" alignment="left"></q2-checkbox>
<q2-checkbox-group id="options-group" label="Options">
<q2-checkbox label="Option 1" alignment="left" value="opt-1"></q2-checkbox>
<q2-checkbox label="Option 2" alignment="left" value="opt-2"></q2-checkbox>
<q2-checkbox label="Option 3" alignment="left" value="opt-3"></q2-checkbox>
</q2-checkbox-group>
<script>
console.log("HTML PREVIEW SCRIPT TRIGGERED");
const selectAll = document.querySelector('#select-all');
const group = document.querySelector('#options-group');
// When an individual checkbox changes, update select-all state
group.addEventListener('tctChange', function (e) {
const values = Object.values(e.detail);
const allChecked = values.every(Boolean);
const noneChecked = values.every(function (v) { return !v; });
selectAll.indeterminate = !allChecked && !noneChecked;
selectAll.checked = allChecked;
});
// When select-all is clicked, update all checkboxes
selectAll.addEventListener('tctChange', function (e) {
const shouldCheck = selectAll.indeterminate ? true : e.detail.checked;
const newValue = {};
group.querySelectorAll('q2-checkbox').forEach(function (cb) {
newValue[cb.value] = shouldCheck;
});
group.value = newValue;
selectAll.indeterminate = false;
// Delay to run after the component's internal change handler
setTimeout(function () { selectAll.checked = shouldCheck; }, 1);
});
</script>
Provide clean examples of how to compose multiple components together in order to achieve a specific visual outcome that is curated and maintained by Tecton.
End-to-end examples of common banking forms — account registration, card controls, secure message, and check deposit — built with Tecton components and the layout rules from Designing Forms.
The following CSS variables are available to override the default theme styles of the q2-checkbox-group component.
Many Tecton components consume other components to maintain visual and functional consistency. If you are looking for a CSS variable you think should exist but are not seeing it, it may be defined in one of the dependent components below. Either way, if you think it's something we should expose more conveniently, let us know!
This component uses other components in the Tecton library, including:
q2-iconThe changelog provides a detailed history of new features, improvements, and bug fixes going back to Tecton 1.30.0. If the button is disabled, it indicates there have been no detectable changes since then.