Checkbox Group

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 implements 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.

1<aura:component>
2  <aura:attribute
3    name="options"
4    type="List"
5    default="[
6    {'label': 'Ross', 'value': 'option1'},
7    {'label': 'Rachel', 'value': 'option2'},
8    ]"
9  />
10  <aura:attribute name="value" type="List" default="option1" />
11  <lightning:checkboxGroup
12    aura:id="mygroup"
13    name="checkboxGroup"
14    label="Checkbox Group"
15    options="{! v.options }"
16    value="{! v.value }"
17    onchange="{! c.handleChange }"
18    required="true"
19  />
20</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").

1({
2  handleChange: function (cmp, event) {
3    var changeValue = event.getParam("value");
4    alert(changeValue);
5  },
6});

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 messageWhenValueMissing 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 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<aura:component>
2  <aura:attribute
3    name="options"
4    type="List"
5    default="[
6            {'label': 'Red', 'value': 'red'},
7            {'label': 'Green', 'value': 'green'},
8            {'label': 'Blue', 'value': 'blue'}                                                        
9            ]"
10  />
11  <aura:attribute name="value" type="List" default="" />
12  <aura:attribute
13    name="message"
14    type="String"
15    default="You haven't selected a color"
16  />
17
18  <lightning:checkboxGroup
19    aura:id="colors"
20    label="Select a color"
21    options="{! v.options }"
22    value="{! v.value }"
23    required="true"
24  />
25
26  <lightning:button label="Check validity" onclick="{!c.handleValidity}" />
27  <p>{!v.message}</p>
28</aura:component>

checkValidity() 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 invalid fields, use the reportValidity() method.

1({
2  handleValidity: function (cmp, event) {
3    var checkboxValidity = cmp.find("colors").get("v.validity");
4    if (checkboxGroup.checkValidity()) {
5      cmp.set("v.message", "That's a great selection!");
6    } else {
7      // Shows the error immediately without user interaction
8      checkboxGroup.reportValidity();
9      cmp.set("v.message", "Select your favorite color and try again.");
10    }
11  },
12});

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

lightning:checkboxGroup 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.