Checkbox Group

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

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

If the disabled attribute is set, 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.

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.

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

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. Note that 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" displayed when a selection on a checkbox group is required and no option is selected, use the message-when-value-missing attribute. This message is displayed 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.

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 display error messages on an invalid checkbox group, use the reportValidity() method.

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

lightning-checkbox-group implements the checkbox blueprint in the Salesforce Lightning Design System (SLDS).

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 does not 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 displays 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 using an SLDS class.

Component styling hooks use the --slds-c-* prefix and change styling for specific elements or properties of a component. Component-specific styling isn’t recommended, because it’s unsupported for SLDS 2, but existing customizations still work with the original SLDS. If you use component styling hooks, limit the components to SLDS themes until SLDS 2 and the Salesforce Cosmos theme become generally available. See Checkbox: Styling Hooks Overview for documentation on component-specific hooks for this component.

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.