Checkbox Button

Checkbox buttons present one or more options with an alternative visual 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.

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.

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

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.

Set the element's checked property to true.

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

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.

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.