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.

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

Design

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.

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.

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

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

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.

<template>
    <lightning-input
        type="checkbox-button"
        data-element="subscribe-checkbox"
        label="Subscribe"
    >
    </lightning-input>
    <lightning-button
        label="Subscribe"
        onclick={handleSubscribe}
    ></lightning-button>
</template>

Set the element's checked property to true.

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.

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

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.

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.

Custom Events

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.

See Also

lightning-input

:::::

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

:::::

::::::