Checkbox Button

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

1<template>
2    <lightning-input
3        type="checkbox-button"
4        label="Add pepperoni"
5        checked
6        value="pepperoni"
7    >
8    </lightning-input>
9    <lightning-input type="checkbox-button" label="Add salami" value="salami">
10    </lightning-input>
11</template>

lightning-input implements designs in the Salesforce Lightning Design System (SLDS). The input types adapt to SLDS 1 or SLDS 2 styling based on the org’s theme or the container app that you use.

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.

1<template>
2    <lightning-input
3        type="checkbox-button"
4        label="Red"
5        onchange={handleCheckboxChange}
6    >
7    </lightning-input>
8    <lightning-input
9        type="checkbox-button"
10        label="Blue"
11        onchange={handleCheckboxChange}
12    >
13    </lightning-input>
14    <lightning-input
15        type="checkbox-button"
16        label="Green"
17        onchange={handleCheckboxChange}
18    >
19    </lightning-input>
20
21    <p>Checked items: {selection}</p>
22</template>

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

1import { LightningElement } from "lwc";
2
3export default class CheckboxExample extends LightningElement {
4  selection;
5
6  handleCheckboxChange() {
7    // Query the DOM
8    const checked = Array.from(this.template.querySelectorAll("lightning-input"))
9      // Filter down to checked items
10      .filter((element) => element.checked)
11      // Map checked items to their labels
12      .map((element) => element.label);
13    this.selection = checked.join(", ");
14  }
15}

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.

1<template>
2    <lightning-input
3        type="checkbox-button"
4        data-element="subscribe-checkbox"
5        label="Subscribe"
6    >
7    </lightning-input>
8    <lightning-button
9        label="Subscribe"
10        onclick={handleSubscribe}
11    ></lightning-button>
12</template>

Set the element’s checked property to true.

1import { LightningElement } from "lwc";
2
3export default class CheckboxExample extends LightningElement {
4  handleSubscribe(event) {
5    this.template.querySelectorAll('[data-element="subscribe-checkbox"]').forEach((element) => {
6      element.checked = true;
7    });
8  }
9}

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

1<template>
2  <lightning-input
3    type="checkbox-button"
4    label="Agree to Terms and Conditions"
5    required
6    lwc:ref="termsCheckbox"
7    message-when-value-missing="Please accept the terms and conditions"
8  >
9  </lightning-input>
10  <lightning-button label="Submit" onclick={handleSubmit}></lightning-button>
11</template>

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.

1import { LightningElement } from "lwc";
2
3export default class CheckboxButtonValidation extends LightningElement {
4  handleSubmit() {
5    const checkboxButton = this.refs.termsCheckbox;
6    console.log(checkboxButton.validity.valid); // Returns true or false
7    if (!checkboxButton.checkValidity()) {
8      checkboxButton.reportValidity();
9      return;
10    }
11    // Proceed with form submission
12  }
13}

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

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.

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.

change

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

The change event returns this event.target parameter.

The event properties are as follows.

lightning-input

For this component’s attributes and methods, see the lightning-input Specifications tab.