# Switch

**`sonic-switch`** is a toggle-styled [Checkbox](/core/components/ui/form/checkbox) in `unique` mode: when on, it stores its `value` under `name` in the **`formDataProvider`** data; when off, it stores `null`. Switches sharing a `name` behave as one choice, so give independent switches distinct names. Label goes in the default slot or `label`, helper text in the `description` slot.

## Basic example

<sonic-code>
  <template>
    <div formDataProvider="switch-basic-demo" class="grid gap-2">
      <sonic-switch name="notifications" value="on" checked>
        Notifications
        <span slot="description">Get an alert when your gate changes.</span>
      </sonic-switch>
      <div>Value: <sonic-value dataProvider="switch-basic-demo" key="notifications"></sonic-value></div>
    </div>
  </template>
</sonic-code>

## Size

With no `size`, the switch follows `md` (1rem).

<sonic-code>
  <template>
    <div class="grid gap-2">
      <sonic-switch size="2xs">2xs</sonic-switch>
      <sonic-switch size="xs">xs</sonic-switch>
      <sonic-switch size="sm">sm</sonic-switch>
      <sonic-switch>Default</sonic-switch>
      <sonic-switch size="lg">lg</sonic-switch>
      <sonic-switch size="xl">xl</sonic-switch>
      <sonic-switch size="2xl">2xl</sonic-switch>
    </div>
  </template>
</sonic-code>

## Checked and disabled

`checked` sets the initial state. `disabled` blocks interaction and dims the control.

<sonic-code>
  <template>
    <div class="grid gap-2">
      <sonic-switch checked>Checked</sonic-switch>
      <sonic-switch disabled>Disabled</sonic-switch>
      <sonic-switch disabled checked>Disabled and checked</sonic-switch>
      <sonic-switch>I accept the <sonic-link href="#" class="underline">terms</sonic-link></sonic-switch>
    </div>
  </template>
</sonic-code>

## Filtering a list

On, the switch writes `status=delayed` to the store used as `dataFilterProvider` by a `sonic-queue`; off, it writes `null` and the filter is dropped.

<docs-lit-demo for="docs-flight-delayed-switch-demo"></docs-lit-demo>

## API reference

| Attribute | Values | Description |
|----------|---------|-------------|
| `name` | string | Key in the form data (dot notation supported) |
| `value` | string | Value stored when on |
| `formDataProvider` | string | Form data id; inherited from the closest ancestor when omitted |
| `checked` | boolean | Initial state |
| `unsetOnDisconnect` | boolean | Removes the value from the data when the element is removed |
| `label` | string (HTML) | Label, rendered before the default slot |
| `description` | string (HTML) | Helper text, rendered in the `description` slot |
| `size` | `2xs` … `2xl` · `inherit` (default `md`) | Font size and track size |
| `disabled` | boolean | Blocks interaction |
| `required` | boolean | Native validation on form submit |
| `autofocus` | boolean | Focuses the input on load |
| `data-aria-label` · `data-aria-labelledby` | string | Forwarded to the inner input as `aria-label` / `aria-labelledby` |

| Slot | Description |
|------|-------------|
| *(default)* | Label content (text, links) |
| `description` | Helper text under the label |

Fires a `change` event on each click.