Checkbox Toggle

lightning-input type="toggle"

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

:::::

:::::tab

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.

<template>
    <lightning-input type="toggle" label="Toggle value" checked>
    </lightning-input>
</template>

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.

<template>
    <div style="width:fit-content">
        <lightning-input type="toggle" label="Toggle value" checked>
        </lightning-input>
    </div>
</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

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

<template>
    <lightning-input
        type="toggle"
        label="Email Notifications"
        checked={isEmailEnabled}
        onchange={handleEmailChange}
        message-toggle-active="On"
        message-toggle-inactive="Off"
    >
    </lightning-input>
    <lightning-input
        type="toggle"
        label="SMS Notifications"
        checked={isSmsEnabled}
        onchange={handleSmsChange}
        message-toggle-active="On"
        message-toggle-inactive="Off"
    >
    </lightning-input>
    <lightning-input
        type="toggle"
        label="Push Notifications"
        checked={isPushEnabled}
        onchange={handlePushChange}
        message-toggle-active="On"
        message-toggle-inactive="Off"
    >
    </lightning-input>

    <p>Enabled notifications: {enabledNotifications}</p>
</template>

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

import { LightningElement } from "lwc";

export default class ToggleExample extends LightningElement {
  isEmailEnabled = false;
  isSmsEnabled = false;
  isPushEnabled = false;

  handleEmailChange(event) {
    this.isEmailEnabled = event.target.checked;
  }

  handleSmsChange(event) {
    this.isSmsEnabled = event.target.checked;
  }

  handlePushChange(event) {
    this.isPushEnabled = event.target.checked;
  }

  get enabledNotifications() {
    const enabled = [];
    if (this.isEmailEnabled) enabled.push("Email");
    if (this.isSmsEnabled) enabled.push("SMS");
    if (this.isPushEnabled) enabled.push("Push");
    return enabled.length > 0 ? enabled.join(", ") : "None";
  }
}

Input Validation

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.

<template>
  <lightning-input
    type="toggle"
    label="Accept terms"
    message-toggle-active="Accepted"
    message-toggle-inactive="Not accepted"
    required
    lwc:ref="termsToggle"
  >
  </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 toggle, use the checkValidity() method. If the value isn't valid, the reportValidity() method shows the error message below the toggle.

import { LightningElement } from "lwc";

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

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

Component Styling

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

Variants

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.

note: The label-stacked variant isn't supported for the checkbox toggle.

Utility Classes

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

Styling Hooks

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.

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

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.

:::::

::::::