Switch
Native checkboxes styled as on/off switches.
When to use
Use a switch for a binary setting with an immediate effect, such as enabling notifications. Use Checkbox for an independent choice that is applied only when a form is submitted.
Default
Combine .form-switch with a native .form-switch-input.
<div class="form-switch">
<input class="form-switch-input" id="switchDefault" name="switchDefault" type="checkbox" />
<label class="form-label" for="switchDefault">Default switch</label>
</div>Checked
<div class="form-switch">
<input
class="form-switch-input"
id="switchChecked"
name="switchChecked"
type="checkbox"
checked />
<label class="form-label" for="switchChecked">Checked switch</label>
</div>Invalid
Use aria-invalid="true" and link adjacent feedback with aria-describedby and its id.
Please enable this option.
<div>
<div class="form-switch">
<input
class="form-switch-input is-invalid"
id="switchInvalid"
name="switchInvalid"
type="checkbox"
aria-invalid="true"
aria-describedby="switchInvalidFeedback" />
<label class="form-label" for="switchInvalid">Invalid switch</label>
</div>
<div class="invalid-feedback" id="switchInvalidFeedback">Please enable this option.</div>
</div>Disabled
<div class="form-switch">
<input
class="form-switch-input"
id="switchDisabled"
name="switchDisabled"
type="checkbox"
disabled />
<label class="form-label" for="switchDisabled">Disabled switch</label>
</div>Accessibility and behavior
- Keep a visible label connected to the native checkbox with
forandid. Use a stable setting name so its meaning does not change when checked. - Tab moves to enabled switches and Space toggles the focused control. Keep native checked state, the visible focus indicator and application state synchronized.
- Use native
disabledwhen unavailable. For native form submission, only checked, enabled inputs with anamecontribute their value; unchecked values are omitted. - Apply validation state to the input and connect feedback with
aria-describedby. The switch styles do not persist settings or perform validation.
CSS variables
Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.
| Token | Default | Purpose | Scope / state |
|---|---|---|---|
--form-switch-gap | var(--spacer-2) | Space between the switch and label. | .form-switch |
--form-switch-input-width | 2.5rem | Switch track width. | .form-switch-input |
--form-switch-input-height | 1.25rem | Switch track height. | .form-switch-input |
--form-switch-input-padding | 0.125rem | Space between the thumb and the track border. | .form-switch-input |
--form-switch-input-bg-color | var(--bg-highlight) | Unchecked track background. | .form-switch-input |
--form-switch-input-border-width | var(--border-width) | Track border thickness. | .form-switch-input |
--form-switch-input-border-color | var(--control-border-color) | Unchecked track border. | .form-switch-input |
--form-switch-input-border-radius | 9999px | Track corner radius. | .form-switch-input |
--form-switch-input-checked-bg-color | var(--primary) | Checked track background. | .form-switch-input (checked) |
--form-switch-input-checked-border-color | var(--primary) | Checked track border. | .form-switch-input (checked) |
--form-switch-thumb-size | 1rem | Thumb diameter. | .form-switch-input |
--form-switch-thumb-bg-color | var(--bg-surface) | Thumb background. | .form-switch-input |
--form-switch-thumb-box-shadow | var(--shadow-sm) | Thumb shadow. | .form-switch-input |
--form-switch-thumb-checked-translate-x | calc(var(--form-switch-input-width) - var(--form-switch-thumb-size) - (var(--form-switch-input-padding) * 2) - (var(--form-switch-input-border-width) * 2)) | Thumb travel when checked; RTL reverses the direction. | .form-switch-input (checked) |
--form-switch-disabled-bg-color | var(--disabled-bg-color) | Background color while disabled. | .form-switch-input (disabled) |
--form-switch-disabled-border-color | var(--disabled-border-color) | Border color while disabled. | .form-switch-input (disabled) |
--form-switch-disabled-thumb-bg-color | var(--disabled-text-color) | Thumb background while disabled. | .form-switch-input (disabled) |
--form-switch-focus-outline-width | var(--focus-outline-width) | Focus ring thickness. | .form-switch-input (focus) |
--form-switch-focus-outline-style | var(--focus-outline-style) | Focus ring line style. | .form-switch-input (focus) |
--form-switch-focus-outline-color | var(--focus-outline-color) | Focus ring color. | .form-switch-input (focus) |
--form-switch-focus-outline-offset | var(--focus-offset) | Distance between the focus ring and control. | .form-switch-input (focus) |
--form-switch-transition-duration | var(--transition-duration) | Duration of visual state transitions. | .form-switch |
--form-switch-transition-easing | var(--transition-easing) | Timing curve for visual state transitions. | .form-switch |