# Switch
> Generated from switch.contract.json — do not edit by hand.

A single setting that takes effect immediately — on or off.

Tier: **leaf-lit**. Frameworks: HTML (paste-and-run, no build step) · React · Vue 3.

Surfaces: editor, dashboard, settings, audience.

## Props
| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `checked` | boolean | `false` | On/off state (reflected) |
| `disabled` | boolean | `false` | Non-interactive |
| `loading` | boolean | `false` | Spinner in the knob; blocks toggle while busy (aria-busy) |
| `size` | 'default' | 'small' | `default` | Track 44×22 (default) or 28×16 (small) |
| `on-text` | string | `—` | Text shown inside the track when on |
| `off-text` | string | `—` | Text shown inside the track when off |
| `on-icon` | icon name | `—` | DS icon shown inside the track when on (wins over on-text) |
| `off-icon` | icon name | `—` | DS icon shown inside the track when off (wins over off-text) |
| `change` | CustomEvent<{checked}> | `—` | Composed event on toggle; read e.detail.checked |

## Visual standard (measured)
- Track: 44×22 (small 28×16) · radius pill · 1px #D4D4D4 border
- Knob: 18×18 white circle, slides 20px (small 12×12, slides 12px)
- Off: track #F7F7F7 (gray-20)
- On: track #6A1EBB (primary)
- Disabled: 40% opacity, not-allowed
- Loading: system-circle-notch spinner rides in the knob; interaction blocked
- Children: optional text or icon inside the track, away from the knob (checked ↔ unchecked)

## When to use
- **Switch** — a single setting that applies immediately — no save step
- **Checkbox** — options saved together as a group, or expressing consent
- **Radio** — exactly one from a small mutually-exclusive set

Never mix switches and checkboxes in one group. The label names what the setting controls as a noun phrase; the switch communicates the action — don't prefix the label with Enable/Turn on. Reach for `loading` on an async setting that may fail, `size=small` in a dense list, and checked/unchecked children only when the on/off meaning isn't obvious from context.