# Switch

An on/off toggle: a native checkbox `input` with `role='switch'`, styled as a track and thumb (`cl-switch-thumb`). The ref and other props go to the input (`cl-switch-input`). Inside a `Field` it takes the field id, label, disabled, required, invalid and message wiring.

## Use for

- turning a setting on or off
- a toggle in a settings row or form

## Practices

- Do: Wrap it in `Field.Root` with a `Field.Label`, or pass `aria-label` or `aria-labelledby`.
- Do: Control it with `checked` and `onChange`, as a checkbox.

## API reference

### Switch

Renders a `span` around the input and thumb. Carries `data-size` and `data-disabled`.

Slot: `cl-switch`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'sm' \| 'md'` | `'md'` | `sm` or `md`. |
| `disabled` | `boolean` |  | Disables the input. Inside a `Field`, the field's `disabled` wins. |

## Examples

### In a field

```tsx
<Field.Root orientation='horizontal'>
  <Switch checked={enabled} onChange={event => setEnabled(event.currentTarget.checked)} />
  <Field.Content>
    <Field.Label>Email notifications</Field.Label>
  </Field.Content>
</Field.Root>
```

## Related

- [Field](/docs/components/field.md)
