lightning:checkboxGroup

A checkbox group that enables selection of single or multiple options. This component requires API version 41.0 and later.

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

If the required attribute is set to true, 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 messageWhenValueMissing attribute.

If the disabled attribute is set to true, checkbox selections can't be changed.

This component inherits styling from Checkbox in the Lightning Design System.

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

<aura:component>
    <aura:attribute name="options" type="List" default="[
    {'label': 'Ross', 'value': 'option1'},
    {'label': 'Rachel', 'value': 'option2'},
    ]"/>
    <aura:attribute name="value" type="List" default="option1"/>
    <lightning:checkboxGroup
        aura:id="mygroup"
        name="checkboxGroup"
        label="Checkbox Group"
        options="{! v.options }"
        value="{! v.value }"
        onchange="{! c.handleChange }"
        required="true" />
</aura:component>
        

You can check which values are selected by using cmp.find("mygroup").get("v.value"). To retrieve the values when a checkbox is selected or deselected, use the onchange event handler and call event.getParam("value").

({
    handleChange: function (cmp, event) {
        var changeValue = event.getParam("value");
        alert(changeValue);
    }
});

Usage Considerations

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

Accessibility

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.

Methods

This component supports the following method.

checkValidity(): Returns the valid property value (Boolean) on the ValidityState object to indicate whether the checkbox group has any validity errors.

Attributes

Attribute Name Attribute type Description Required?
body Component[] The body of the component. In markup, this is everything in the body of the tag.
class String A CSS class for the outer element, in addition to the component's base classes.
title String Displays tooltip text when the mouse moves over the element.
name String The name of the checkbox group. Yes
label String Text label for the checkbox group. Yes
options List Array of label-value pairs for each checkbox. Yes
value String[] The list of selected checkboxes. Each array entry contains the value of a selected checkbox. The value of each checkbox is set in the options attribute. Yes
messageWhenValueMissing String Optional message displayed when no checkbox is selected and the required attribute is set to true.
required Boolean Set to true if at least one checkbox must be selected. This value defaults to false.
disabled Boolean Set to true if the checkbox group is disabled. Checkbox selections can't be changed for a disabled checkbox group. This value defaults to false.
onblur Action The action triggered when the checkbox group releases focus.
onchange Action The action triggered when a checkbox value changes.
onfocus Action The action triggered when the checkbox group receives focus.