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