---
url: /docs/components/switch/frameworks/elements.md
---
# Switch - Elements

The Switch component allows users to toggle between two states.

## Accessibility

The internal control is rendered as a native `button` with `role="switch"` and `aria-checked` / `aria-disabled`.

## Usage

`<w-switch>` is a form-associated toggle component.

* It reflects its `name`, `value`, `checked`, and `disabled` properties to attributes.
* It dispatches a bubbling `change` `CustomEvent` when toggled (when not disabled).
* When used in a form, the control submits `value` only when `checked` is `true` (otherwise it submits nothing).

## Examples

```html
<w-switch id="demo-switch" name="marketing" value="yes"></w-switch>

<script>
  const el = document.querySelector('#demo-switch');
  el.addEventListener('change', (event) => {
    // event.detail = { checked: boolean, value: string | null }
    console.log('changed', event.detail);
  });
</script>
```

## Styling API

## `<w-switch>` API

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

### Properties

| Name | Type | Default | Summary |
|-|-|-|-|
| checked | `boolean` | `false` | Whether the switch is on (checked). |
| disabled | `boolean` | `false` | Whether the switch is disabled. |
| name | `string` | `-` | Name used when submitting an HTML form. |
| resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
| tabindex | `number` | `0` | - |
| value | `string` | `-` | Value submitted when the switch is checked. |

### Property Details

#### checked

Whether the switch is on (checked).

* Type: `boolean`
* Default: `false`

#### disabled

Whether the switch is disabled.

* Type: `boolean`
* Default: `false`

#### name

Name used when submitting an HTML form.

* Type: `string`
* Default: `-`

#### resetFormControl (JS only)

* Type: `resetFormControl() => void`
* Default: `-`

#### tabindex

* Type: `number`
* Default: `0`

#### value

Value submitted when the switch is checked.

The component reports `null` as the value in the `change` event when `value` is an empty string.

* Type: `string`
* Default: `-`

### Events

#### change

Dispatched when the switch toggles. Includes boolean `checked` and string/null `value` on `details`.

* Type: [`WarpSwitchChangeEvent`](#warpswitchchangeevent)

### Types

#### WarpSwitchChangeEvent

`{ detail: { checked: boolean, value: null | string }, initCustomEvent: {  }, bubbles: boolean, cancelBubble: boolean, cancelable: boolean, composed: boolean, currentTarget: null | { addEventListener: {  }, dispatchEvent: {  }, removeEventListener: {  } }, defaultPrevented: boolean, eventPhase: number, isTrusted: boolean, returnValue: boolean, srcElement: null | { addEventListener: {  }, dispatchEvent: {  }, removeEventListener: {  } }, target: null | { addEventListener: {  }, dispatchEvent: {  }, removeEventListener: {  } }, timeStamp: number, type: string, composedPath: {  }, initEvent: {  }, preventDefault: {  }, stopImmediatePropagation: {  }, stopPropagation: {  }, NONE: 0, CAPTURING_PHASE: 1, AT_TARGET: 2, BUBBLING_PHASE: 3 }`