---
schema_version: "1"
id: 342cb0112e2ab4b3d498dcb6b960ad13f92c9c875f8526d05942cb19095c3e1e
title: Checkbox Toggle
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/lightning-base-components/lightning-design-system/guides/lwc/components/lightning/checkboxToggle/lightning-checkbox-toggle.md
canonical_url: https://developer.salesforce.com/docs/platform/lightning-component-reference/guide/lightning-checkbox-toggle.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 76207f518e066dcdcfd9e7ab9f2cf8fc49baa268e5310562f523b18687aedd67
products:
  - Lightning Component Reference
---

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

<!-- prettier-ignore-start -->
```html
<template>
    <lightning-input type="toggle" label="Toggle value" checked>
    </lightning-input>
</template>
```
<!-- prettier-ignore-end -->

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.

<!-- prettier-ignore-start -->
```html
<template>
    <div style="width:fit-content">
        <lightning-input type="toggle" label="Toggle value" checked>
        </lightning-input>
    </div>
</template>
```
<!-- prettier-ignore-end -->

## Design

`lightning-input` implements designs in the Salesforce Lightning Design System (SLDS). The input types adapt to SLDS 1 or [SLDS 2 styling](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm) based on the org's theme or the container app that you use.

| Input Type | SLDS 1                                                                             | SLDS 2                                                                              |
| ---------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| toggle     | [Checkbox Toggle](https://v1.lightningdesignsystem.com/components/checkbox-toggle) | [Checkbox Toggle](https://www.lightningdesignsystem.com/components/checkbox-toggle) |

## Handle Selections

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

<!-- prettier-ignore-start -->
```html
<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>
```
<!-- prettier-ignore-end -->

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

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

<!-- prettier-ignore -->
```html
<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](/docs/platform/lightning-component-reference/guide/lightning-input.html).

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

```javascript
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](https://v1.lightningdesignsystem.com/utilities/alignment) 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](https://v1.lightningdesignsystem.com/components/overview/) for available component styling hooks.

For more information, see [Style Components Using Lightning Design System Styling Hooks](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-css-custom-properties) 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](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).

## Custom Events

**`change`**

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

The `change` event returns this `event.target` parameter.

| Parameter | Type    | Description                                                                                                                      |
| --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| checked   | boolean | The value of `checked` attribute. See [Handle Selections](#handle-selections) for an example of working with an array of inputs. |

The event properties are as follows.

| Property   | Value | Description                                                                                               |
| ---------- | ----- | --------------------------------------------------------------------------------------------------------- |
| bubbles    | true  | This event bubbles up through the DOM.                                                                    |
| cancelable | false | This event has no default behavior that can be canceled. You can't call `preventDefault()` on this event. |
| composed   | true  | This event propagates outside of the component in which it was dispatched.                                |

## See Also

[`lightning-input`](/docs/platform/lightning-component-reference/guide/lightning-input.html)


:::::

:::::tab
For this component's attributes and methods, see the [`lightning-input` Specifications tab](/docs/platform/lightning-component-reference/guide/lightning-input.html?type=Specifications).


:::::

::::::