Checkbox Group

A lightning-checkbox-group component represents a checkbox group that enables selection of single or multiple options.

If you specify the required attribute, at least one checkbox must be selected. When a user interacts with the checkbox group and doesn’t make a selection, an error message appears. You can provide a custom error message by using the message-when-value-missing attribute.

If you specify the disabled attribute, checkbox selections can’t be changed.

This example creates a checkbox group with two options and option1 is selected by default. At least one checkbox must be selected because the required attribute is specified.

1<template>
2    <lightning-checkbox-group
3        name="checkboxGroup"
4        label="Checkbox Group"
5        options={options}
6        value={value}
7        onchange={handleChange}
8        required
9    >
10    </lightning-checkbox-group>
11</template>

The value attribute contains an array of checkboxes. To select a checkbox, pass in its value to the value attribute. In this example, only option1 is selected.

1//mycomponentname.js
2
3import { LightningElement } from "lwc";
4export default class MyComponentName extends LightningElement {
5  options = [
6    { label: "One", value: "option1" },
7    { label: "Two", value: "option2" },
8  ];
9
10  // Select option1 by default
11  value = ["option1"];
12
13  handleChange(event) {
14    const changeValue = event.detail.value;
15    alert(changeValue);
16  }
17}

To retrieve the values when a checkbox is selected or deselected, use event.detail.value in the change event handler.

lightning-checkbox-group implements the checkbox blueprint in the Salesforce Lightning Design System (SLDS). The checkbox adapts to SLDS 1 or SLDS 2 styling based on the org’s theme or the container app that you use.

To create checkboxes, pass in the following properties to the options attribute.

Client-side input validation is available for this component. For example, an error message is displayed when the checkbox group is marked required and no option is selected. A disabled checkbox group is always valid.

The validation occurs for the checkbox group, not for an individual checkbox. To override the default message “Complete this field” that appears when a selection on a checkbox group is required and no option is selected, use the message-when-value-missing attribute. This message appears when you remove focus from the checkbox group.

The validity attribute returns the ValidityState object, with the following supported properties.

• valid: Returns true if the checkbox group meets all its validation constraints.
• valueMissing: Returns true if a selection in the checkbox group is required but no checkbox is selected.

Other properties such as badInput are not supported.

This example creates a checkbox group that requires a selection and a button that checks validity when clicked.

1<template>
2    <lightning-checkbox-group
3        label="Select a color"
4        options={options}
5        value={value}
6        required
7    ></lightning-checkbox-group>
8    <lightning-button
9        label="Check validity"
10        onclick={handleValidity}
11    ></lightning-button>
12</template>

For checkbox groups that are required, the checkValidity() method returns true if at least one checkbox is selected, or false if none is selected. Calling checkValidity() is equivalent to returning validity.valid on the checkbox group.

To programmatically show error messages on an invalid checkbox group, use the reportValidity() method.

1import { LightningElement } from "lwc";
2
3export default class CheckboxGroupRequiredValidity extends LightningElement {
4  value = [];
5  message = "";
6
7  get options() {
8    return [
9      { label: "Red", value: "red" },
10      { label: "Green", value: "green" },
11      { label: "Blue", value: "blue" },
12    ];
13  }
14  handleValidity(e) {
15    var checkboxGroup = this.template.querySelector("lightning-checkbox-group");
16    if (checkboxGroup.checkValidity()) {
17      this.message = "That's a great selection!";
18    } else {
19      // Shows the error immediately without user interaction
20      checkboxGroup.reportValidity();
21      this.message = "Select your favorite color and try again.";
22    }
23  }
24}

For custom validity error messages, specify the message by using setCustomValidity() and reportValidity(). setCustomValidity() overrides the error message that you provide with the message-when-value-missing attribute. For more information, see the lightning-input documentation.

You can use a combination of the variant and class attributes to customize the checkbox group.

Use the variant attribute with one of these values to apply different label positioning.

• label-hidden hides the checkbox group label but make it available to assistive technology. This variant doesn’t hide the option labels.
• label-inline horizontally aligns the checkbox group label and options.
• label-stacked places the checkbox group label above the options.
• standard is the default value, which shows the checkbox group label above the options.

To apply additional styling, use the SLDS utility classes with the class attribute.

This example adds a box theme around the checkbox group by using an SLDS class.

1<lightning-checkbox-group
2    class="slds-box"
3    label="Select a color"
4    options={options}
5    value={value}
6>
7</lightning-checkbox-group>

Component styling hooks provide CSS custom properties that use the --slds-c-* prefix and they change styling for specific elements or properties of a component. Component styling hooks are supported for SLDS 1 only. See the SLDS 1 component blueprints for available component styling hooks.

For more information, see Style Components Using Lightning Design System Styling Hooks in the Lightning Web Components Developer Guide.

lightning-checkbox-group is useful for grouping a set of checkboxes. If you have a single checkbox, use lightning-input type="checkbox" instead.

The checkbox group is nested in a fieldset element that contains a legend element. The legend contains the label value. The fieldset element enables grouping of related checkboxes to facilitate tabbing navigation and speech navigation for accessibility purposes. Similarly, the legend element improves accessibility by enabling a caption to be assigned to the fieldset.