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.

HTML
<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

HTML
<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.

HTML
<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

HTML
<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 for and id. 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 disabled when unavailable. For native form submission, only checked, enabled inputs with a name contribute 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.

TokenDefaultPurposeScope / state
--form-switch-gapvar(--spacer-2)Space between the switch and label..form-switch
--form-switch-input-width2.5remSwitch track width..form-switch-input
--form-switch-input-height1.25remSwitch track height..form-switch-input
--form-switch-input-padding0.125remSpace between the thumb and the track border..form-switch-input
--form-switch-input-bg-colorvar(--bg-highlight)Unchecked track background..form-switch-input
--form-switch-input-border-widthvar(--border-width)Track border thickness..form-switch-input
--form-switch-input-border-colorvar(--control-border-color)Unchecked track border..form-switch-input
--form-switch-input-border-radius9999pxTrack corner radius..form-switch-input
--form-switch-input-checked-bg-colorvar(--primary)Checked track background..form-switch-input (checked)
--form-switch-input-checked-border-colorvar(--primary)Checked track border..form-switch-input (checked)
--form-switch-thumb-size1remThumb diameter..form-switch-input
--form-switch-thumb-bg-colorvar(--bg-surface)Thumb background..form-switch-input
--form-switch-thumb-box-shadowvar(--shadow-sm)Thumb shadow..form-switch-input
--form-switch-thumb-checked-translate-xcalc(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-colorvar(--disabled-bg-color)Background color while disabled..form-switch-input (disabled)
--form-switch-disabled-border-colorvar(--disabled-border-color)Border color while disabled..form-switch-input (disabled)
--form-switch-disabled-thumb-bg-colorvar(--disabled-text-color)Thumb background while disabled..form-switch-input (disabled)
--form-switch-focus-outline-widthvar(--focus-outline-width)Focus ring thickness..form-switch-input (focus)
--form-switch-focus-outline-stylevar(--focus-outline-style)Focus ring line style..form-switch-input (focus)
--form-switch-focus-outline-colorvar(--focus-outline-color)Focus ring color..form-switch-input (focus)
--form-switch-focus-outline-offsetvar(--focus-offset)Distance between the focus ring and control..form-switch-input (focus)
--form-switch-transition-durationvar(--transition-duration)Duration of visual state transitions..form-switch
--form-switch-transition-easingvar(--transition-easing)Timing curve for visual state transitions..form-switch