Switch
On/off for a setting that applies at once. A native checkbox with role="switch", enhanced after hydration.
Examples
Labels and sizes
<Switch name="enabled" label="Server enabled" checked />
<Switch name="routing" label="Automatic routing" size="sm" />
<Switch label="Write tools" disabled />In a Field, busy
busy shows a spinner in the thumb while a server action confirms the change. autoSubmit posts the surrounding form on toggle.
Use SSE when the server does not answer over HTTP.
<Field id="sse-fallback" label="SSE fallback" inline hint="Use SSE when the server does not answer over HTTP.">
<Switch name="sse" />
</Field>
<Switch aria-label="Server enabled" checked busy />Usage
import { Switch } from '@switchboard/ui'
<form method="post" action={toggleHref}>
<Switch name="enabled" label="Server enabled" checked={server.enabled} autoSubmit />
</form>Props
Every component also takes mix, for css() and mixins applied after its own style.
Switch
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | – | Inline label to the right of the track. |
| checked | boolean | – | Initial state (uncontrolled). |
| name | string | – | Form field name. Posts value when on, nothing when off. |
| value | string | – | Value posted when on. Browser default "on". |
| size | 'sm' | 'md' | 'md' | Track 26 or 32px wide. |
| disabled | boolean | – | Locks the switch. |
| busy | boolean | – | Spinner in the thumb, aria-busy, input locked. |
| autoSubmit | boolean | – | Submits the surrounding form when toggled. |
| required | boolean | – | Native required. |
| aria-label | string | – | Name when there is no label or Field. |
Reads id, aria-describedby and required from a Field. Needs a name: label, aria-label or a Field.
Accessibility
- A native checkbox with role="switch", so screen readers say "on" or "off" and Space toggles it before hydration.
- The visible track is aria-hidden; the input covers the whole label, so the text is clickable too.
- busy sets aria-busy on the label and locks the input until the server answers.
Guidance
Do
- Use a Switch for a setting that applies the moment it changes.
- Label the setting, not the state: "Server enabled", not "On".
Don’t
- Put a Switch in a form that only saves on a button; use a Checkbox.
- Change the label text when the state changes.