Checkbox Toggle

A checkbox toggle presents two values for single selection. Use the message-toggle-active and message-toggle-inactive attributes to specify labels displayed under the toggle for each state. By default, the labels are Active and Inactive. To omit labels, set these attributes to empty strings.

A toggle is similar to a checkbox; it presents a binary choice. However, a toggle is self-contained and is designed to be used in a form with only one field. When you switch a toggle on or off, the change for that item should save immediately.

By default, the toggle component expands to 100% of the available width. To limit the size of the toggle component, wrap it with an element that specifies the appropriate width.

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.

Track the state of each toggle individually using the onchange event. The following example displays the values of the enabled toggles.

Track each toggle state and update the display when any toggle changes.

To ensure the toggle is enabled before form submission, use the required attribute. When required is used, the toggle must be enabled to pass validation.

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

The validity attribute returns an object with read-only boolean properties. For the toggle 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

Use a combination of variants and utility classes to customize your checkbox toggle.

Use the variant attribute with one of these values to position the labels differently relative to the fields.

• standard is the default, which displays the label next to the field.
• label-hidden hides the label but make it available to assistive technology. If you provide a value for field-level-help, the tooltip icon is still displayed.
• label-inline aligns the label and field horizontally.

To apply additional styling, use the SLDS utility classes with the class attribute.

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 for available component styling hooks.

For more information, see Style Components Using Lightning Design System Styling Hooks in the Lightning Web Components Developer Guide.

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

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

If the toggle 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.