---
schema_version: "1"
id: 22aefd6c57f11582a41a170b947fe24540633ed5ccb6c668f7fe70ae69c46182
title: Checkbox Group
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/checkboxGroup/lightning-checkbox-group.md
canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-checkbox-group.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 1b4cb600398f65194a4f95d3c700d15442512e3544ed08e023cd8255ddf899b4
products:
  - Lightning Component Reference
---

# Checkbox Group

**`lightning-checkbox-group`**

A checkbox group that enables selection of single or multiple options.

**For Use In**

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="checkboxGroup" model="lwc" namespace="lightning"}


:::::

:::::tab

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.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-checkbox-group
        name="checkboxGroup"
        label="Checkbox Group"
        options={options}
        value={value}
        onchange={handleChange}
        required
    >
    </lightning-checkbox-group>
</template>
```
<!-- prettier-ignore-end -->

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.

```javascript
//mycomponentname.js

import { LightningElement } from "lwc";
export default class MyComponentName extends LightningElement {
  options = [
    { label: "One", value: "option1" },
    { label: "Two", value: "option2" },
  ];

  // Select option1 by default
  value = ["option1"];

  handleChange(event) {
    const changeValue = event.detail.value;
    alert(changeValue);
  }
}
```

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

## Design

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

|                | SLDS 1                                                                                                                                | SLDS 2                                                                                                          |
| :------------- | :------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Design**     | [Checkbox (Group)](https://v1.lightningdesignsystem.com/components/checkbox/#Group/)                                                  | [Checkbox (Group)](https://www.lightningdesignsystem.com/components/checkbox/#Group/)                           |
| **For Use In** | Lightning Experience, Experience Builder sites, Salesforce mobile app, Lightning Out (Beta), Standalone Lightning app, Mobile Offline | [Lightning Experience](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5) |

## Create Checkboxes

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

| Property | Type   | Description                                                    |
| -------- | ------ | -------------------------------------------------------------- |
| label    | string | The text that appears next to a checkbox.                      |
| value    | string | The string that's used to identify which checkbox is selected. |

## Input Validation

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.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-checkbox-group
        label="Select a color"
        options={options}
        value={value}
        required
    ></lightning-checkbox-group>
    <lightning-button
        label="Check validity"
        onclick={handleValidity}
    ></lightning-button>
</template>
```
<!-- prettier-ignore-end -->

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.

```javascript
import { LightningElement } from "lwc";

export default class CheckboxGroupRequiredValidity extends LightningElement {
  value = [];
  message = "";

  get options() {
    return [
      { label: "Red", value: "red" },
      { label: "Green", value: "green" },
      { label: "Blue", value: "blue" },
    ];
  }
  handleValidity(e) {
    var checkboxGroup = this.template.querySelector("lightning-checkbox-group");
    if (checkboxGroup.checkValidity()) {
      this.message = "That's a great selection!";
    } else {
      // Shows the error immediately without user interaction
      checkboxGroup.reportValidity();
      this.message = "Select your favorite color and try again.";
    }
  }
}
```

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](/docs/platform/lightning-component-reference/guide/lightning-input.html) documentation.

## Component Styling

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

### Variants

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.

### Utility Classes

To apply additional styling, use the SLDS [utility classes](https://v1.lightningdesignsystem.com/utilities/alignment) with the `class` attribute.

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

<!-- prettier-ignore-start -->
```html
<lightning-checkbox-group
    class="slds-box"
    label="Select a color"
    options={options}
    value={value}
>
</lightning-checkbox-group>
```
<!-- prettier-ignore-end -->

### Styling Hooks

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](https://v1.lightningdesignsystem.com/components/overview/) for available component styling hooks.

For more information, see [Style Components Using Lightning Design System Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties) in the Lightning Web Components Developer Guide.


## Usage Considerations

`lightning-checkbox-group` 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`.


:::::

:::::tab
::component-specification{component="checkboxGroup" model="lwc" namespace="lightning"}

:::::

::::::