# Switch (w-switch)

## Description

The Switch component allows users to toggle between two states.

[Warp component reference](https://warp-ds.github.io/docs/components/switch/frameworks/elements)

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

## Accessibility

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

## Examples

<elements-example>

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

</elements-example>

## 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` | `-` | - |
| 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: `-`

#### 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: false | true, value: null | string }, initCustomEvent: {  }, bubbles: false | true, cancelBubble: false | true, cancelable: false | true, composed: false | true, currentTarget: null | { addEventListener: {  }, dispatchEvent: {  }, removeEventListener: {  } }, defaultPrevented: false | true, eventPhase: number, isTrusted: false | true, returnValue: false | true, 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 }`