Switch
Toggle on/off switch built on <input type="checkbox"> with role="switch". Renders as a pill-shaped track with a sliding thumb. Used for boolean settings that take effect immediately (not form submissions) - notifications on/off, dark mode on/off, auto-save on/off.
Usage
When to use
- Boolean settings that apply immediately on toggle
- Feature toggles and preference controls
- Any on/off state where a checkbox would feel like a form submission
When not to use
- Part of a form that requires a submit action - use a checkbox
- More than two states - use radio buttons or a segmented control
- Mutually exclusive choices between labeled options - use radio buttons
Do
- Associate a
<label>with the switch viafor/id - Reflect the current state via
aria-checked(automatic on<input type="checkbox">) - Honor
prefers-reduced-motionfor the thumb animation
Don't
- Use a switch to submit a form
- Rely on color alone to communicate state
- Build a custom div-based switch - use the native checkbox
API
Slots
| Slot | Required | Description |
|---|---|---|
label | Yes | Visible label text for the switch. |
Props
| Prop | Type | Default | Description |
|---|---|---|---|
name | string | - | Name attribute for form submission. |
id | string | - | Associates the control with its label. |
is_checked | boolean | - | Sets the initial checked state. |
is_disabled | boolean | - | Disables the control. |
classes | array | - | Additional CSS class words merged into the root element. |
attributes | object | - | Additional HTML attributes spread on the root element. |
Classes
| Class | Capability | Default | Description |
|---|---|---|---|
.sm | Size | - | Small. |
.md | Size | Yes | Medium. |
.lg | Size | - | Large. |
Examples
Sizes
Sm, default, and lg variants stacked vertically. The track and thumb scale together.
Checked
Pre-checked switch demonstrating the "on" treatment.
Wrapping
The consumer-authored <label><input type="checkbox" role="switch"> Text</label> form. Semetrika's twig template emits the sibling form (<input> + <label>), but page authors and CMS integrations may hand-write the wrapping form. The wrapping label renders as inline-flex with align-items: center so the pill and the surrounding text share a true vertical center.
Disabled
Disabled switch via the disabled attribute.
Accessibility
- WCAG 2.2 AA
role="switch"on the checkbox inputaria-checkedreflects the toggle state (native checkbox state is exposed automatically)- Visible focus ring for keyboard users
- Label association via
<label>element disabledattribute for disabled state- Animation respects
prefers-reduced-motion
Related
- checkbox - alternative boolean control inside forms