Skip to content

Switch

An on or off setting that takes effect at once, with its state in a word beside it.

<div class="cap-field-options" id="main">
  <label class="cap-switch" data-cap="switch" id="sw-on"><input type="checkbox" role="switch" checked /> Single-key shortcuts <span class="cap-switch-state" aria-hidden="true">On</span></label>
  <label class="cap-switch" data-cap="switch" id="sw-off"><input type="checkbox" role="switch" /> Compact rows <span class="cap-switch-state" aria-hidden="true">Off</span></label>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/switch.css";
import { enhance } from "capsomer/behavior/switch";

enhance();

Usage

<label class="cap-switch" data-cap="switch">
  <input type="checkbox" role="switch" checked /> Single-key shortcuts
  <span class="cap-switch-state" aria-hidden="true">On</span>
</label>
<Switch label="Single-key shortcuts" checked={keys} onCheckedChange={setKeys} />

Examples

Keyboard focus

<p class="cap-muted">Tab to the switch to see focus; Space turns it on or off.</p>
<label class="cap-switch" data-cap="switch" id="sw-focus"><input type="checkbox" role="switch" /> Show times in UTC <span class="cap-switch-state" aria-hidden="true">Off</span></label>

Hover

<div class="cap-field-options">
  <label class="cap-switch" data-cap="switch" id="sw-hover-off"><input type="checkbox" role="switch" /> Sound on new mentions <span class="cap-switch-state" aria-hidden="true">Off</span></label>
  <label class="cap-switch" data-cap="switch" id="sw-hover-on"><input type="checkbox" role="switch" checked /> Weekly digest <span class="cap-switch-state" aria-hidden="true">On</span></label>
</div>

Disabled, with its reason

<div class="cap-field-options">
  <label class="cap-switch" data-cap="switch" id="sw-disabled"><input type="checkbox" role="switch" disabled aria-describedby="sw-disabled-why" /> Email alerts <span class="cap-switch-state" aria-hidden="true">Off</span></label>
  <span class="cap-btn-reason" id="sw-disabled-why">Add an email address in Settings first.</span>
</div>

Pending: the change is being sent

<p class="cap-muted">The switch has not moved yet. It is not disabled, so focus stays.</p>
<label class="cap-switch" data-cap="switch" id="sw-busy"><input type="checkbox" role="switch" aria-busy="true" /> Nightly export<span class="cap-switch-state" aria-hidden="true">Off</span></label>

Small, and invalid

<div class="cap-field-options">
  <label class="cap-switch" data-cap="switch" data-size="sm" id="sw-sm"><input type="checkbox" role="switch" checked /> Dense mode <span class="cap-switch-state" aria-hidden="true">On</span></label>
  <label class="cap-switch" data-cap="switch" id="sw-invalid"><input type="checkbox" role="switch" aria-invalid="true" aria-describedby="sw-invalid-why" /> Public status page <span class="cap-switch-state" aria-hidden="true">Off</span></label>
  <span class="cap-field-error" id="sw-invalid-why">Verify the domain before publishing.</span>
</div>

Comfortable density

<div class="cap-specimen-row" data-density="comfortable">
  <label class="cap-switch" data-cap="switch"><input type="checkbox" role="switch" checked /> Weekly digest <span class="cap-switch-state" aria-hidden="true">On</span></label>
  <label class="cap-switch" data-cap="switch" data-size="sm"><input type="checkbox" role="switch" /> Dense mode <span class="cap-switch-state" aria-hidden="true">Off</span></label>
</div>

API reference

Switch

PropTypeRequiredDoes
labelReactNodeYesA fixed noun: what is switched, never the state ("Single-key shortcuts").
checkedbooleanControlled; leave it out for a switch that keeps its own state.
defaultCheckedboolean
onCheckedChange(checked: boolean) => voidCalled at once with the new state: a switch takes effect without a Save.
onWordstring
offWordstring
busybooleanA request for the change is running: drawn as a dashed outline, and not disabled.
refRef<HTMLInputElement>The input itself (React 19 passes ref as a prop).

And every attribute of <input>.

Functions

FunctionSignatureDoes
stateWord(checked: boolean, on?: string, off?: string): stringThe switch's behavior: keeps the state word beside it true. The word is "On" and "Off" unless the .cap-switch-state element sets its own in data-on and data-off.
syncWord(label: Element): voidWrites the word for one switch's current state.
setSwitch(label: Element, checked: boolean): voidMoves a switch from code (an Undo, a value from the server) and keeps its word true. Fires no change event, so it cannot loop back into the app's own handler.
setBusy(label: Element, busy: boolean): voidMarks a switch pending while a request for its change runs (aria-busy, drawn as a dashed outline), and clears it when the request has answered. The switch is not disabled, so focus stays where it is.
enhance(root?: ParentNode): () => voidAttaches to every [data-cap="switch"] under root that is not attached yet. Returns a function that detaches them all.

CSS variables

VariableDefault
--cap-sw-h20px
--cap-sw-thumb14px
--cap-sw-w36px

Parts and data attributes

ClassIs
.cap-switchthe root
.cap-switch-statea part
AttributeValues
data-sizesm
StateRead from
:checkedthe platform
:disabledthe platform
:focus-visiblethe platform
:hoverthe platform
[aria-busy="true"]an attribute
[aria-invalid="true"]an attribute

Accessibility

KeyDoes
TabMoves to the switch
SpaceTurns it on or off, at once; the word follows
  • A native checkbox, so it is in the tab order, labeled by its <label>, and toggled by Space and by a click anywhere on the label.
  • The whole label is the hit area, at least var(--target) tall.
  • Forced colors: the track and thumb are drawn in CanvasText, and in Highlight when on.