---
schema_version: "1"
id: 2710662a851695f39b0815259c18de68bb0a3dbaaf3c0a12c904b9c7c01b73f7
title: Checkbox Button
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/checkboxButton/lightning-checkbox-button.md
canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-checkbox-button.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: d1b2e79c796b310a696869844b18ba60f45deb8fd04f83b16ad918523ae21cf7
products:
  - Lightning Component Reference
---

# Checkbox Button

**`lightning-input`**
_type="checkbox-button"_

**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="checkboxButton" model="lwc" namespace="lightning"}


:::::

:::::tab

Checkbox buttons present one or more options with an alternative visual
design.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="checkbox-button"
        label="Add pepperoni"
        checked
        value="pepperoni"
    >
    </lightning-input>
    <lightning-input type="checkbox-button" label="Add salami" value="salami">
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-input` implements designs in the Salesforce Lightning Design System (SLDS). The input types adapt to SLDS 1 or [SLDS 2 styling](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm) based on the org's theme or the container app that you use.

| Input Type      | SLDS 1                                                                              | SLDS 2                                                                               |
| --------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| checkbox-button | [Checkbox Button](https://v1.lightningdesignsystem.com/components/checkbox-button/) | [Checkbox Button](https://www.lightningdesignsystem.com/components/checkbox-button/) |

## Handle Selections

When working with checkboxes and toggle
switches, use `this.template.querySelectorAll` to retrieve the array of components. You can
use `.filter` to determine which elements are checked or unchecked. The following
example displays the values of the selected checkboxes.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="checkbox-button"
        label="Red"
        onchange={handleCheckboxChange}
    >
    </lightning-input>
    <lightning-input
        type="checkbox-button"
        label="Blue"
        onchange={handleCheckboxChange}
    >
    </lightning-input>
    <lightning-input
        type="checkbox-button"
        label="Green"
        onchange={handleCheckboxChange}
    >
    </lightning-input>

    <p>Checked items: {selection}</p>
</template>
```
<!-- prettier-ignore-end -->

When you select a checkbox, the `handleCheckboxChange` function updates the `selection` property
to display a list of selected checkboxes.

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

export default class CheckboxExample extends LightningElement {
  selection;

  handleCheckboxChange() {
    // Query the DOM
    const checked = Array.from(this.template.querySelectorAll("lightning-input"))
      // Filter down to checked items
      .filter((element) => element.checked)
      // Map checked items to their labels
      .map((element) => element.label);
    this.selection = checked.join(", ");
  }
}
```

To programmatically set a checkbox or checkbox button to `checked`, query the element using a custom data attribute. You can't query the internal elements of a Lightning web component. This example uses a custom attribute `data-element` to query the element. The checkbox is selected by clicking a button.

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input
        type="checkbox-button"
        data-element="subscribe-checkbox"
        label="Subscribe"
    >
    </lightning-input>
    <lightning-button
        label="Subscribe"
        onclick={handleSubscribe}
    ></lightning-button>
</template>
```
<!-- prettier-ignore-end -->

Set the element's `checked` property to `true`.

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

export default class CheckboxExample extends LightningElement {
  handleSubscribe(event) {
    this.template.querySelectorAll('[data-element="subscribe-checkbox"]').forEach((element) => {
      element.checked = true;
    });
  }
}
```

## Input Validation

To ensure the checkbox button is selected before form submission, use the `required` attribute.

<!-- prettier-ignore -->
```html
<template>
  <lightning-input
    type="checkbox-button"
    label="Agree to Terms and Conditions"
    required
    lwc:ref="termsCheckbox"
    message-when-value-missing="Please accept the terms and conditions"
  >
  </lightning-input>
  <lightning-button label="Submit" onclick={handleSubmit}></lightning-button>
</template>
```

**note:** For the default error messages, see the [`lightning-input` documentation](/docs/platform/lightning-component-reference/guide/lightning-input.html).

To validate the checkbox button, use the `checkValidity()` method. If the value isn't valid, the `reportValidity()` method shows the error message below the checkbox button.

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

export default class CheckboxButtonValidation extends LightningElement {
  handleSubmit() {
    const checkboxButton = this.refs.termsCheckbox;
    console.log(checkboxButton.validity.valid); // Returns true or false
    if (!checkboxButton.checkValidity()) {
      checkboxButton.reportValidity();
      return;
    }
    // Proceed with form submission
  }
}
```

The `validity` attribute returns an object with read-only boolean properties. For the `checkbox-button` type, these attributes apply:

- `badInput` - Indicates that the value is invalid for any input type
- `customError` - Indicates that a custom error has been set using `setCustomValidity()`
- `valueMissing` - Indicates that an empty value is provided when the `required` attribute is set for any input type
- `valid` - True if none of the preceding properties are true

## Usage Considerations

The `label` is always hidden from view and available as assistive text for screen readers. Using the `variant` attribute with the checkbox button has no impact on label display or layout.

Field-level help text isn't supported for the checkbox button.

## Accessibility

When you use the `label` attribute, the component generates a unique ID for the internal `<label>` and uses a standard `for` attribute to link it to the checkbox button.

If you use the `label-hidden` variant, the component maintains the `for` attribute to link between the checkbox button and the label.

If you use the `field-level-help` attribute, the component creates an `aria-describedby` link between the checkbox button and the help tooltip.

If the checkbox button fails validation, the component adds `aria-invalid="true"` and links the error message to the input by using `aria-describedby`.

For additional ARIA attributes that you can use, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).

## Custom Events

**`change`**

The event fired when a value is changed in the input field.

The `change` event returns this `event.target` parameter.

| Parameter | Type    | Description                                                                                                                      |
| --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| checked   | boolean | The value of `checked` attribute. See [Handle Selections](#handle-selections) for an example of working with an array of inputs. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## See Also

[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html)


:::::

:::::tab
For this component's attributes and methods, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).


:::::

::::::