Skip to content

Switch

Stable Available in release assets

Present an on/off preference as a native checkbox with role=switch so keyboard, pointer, validation, and form submission stay canonical.

Switch primary example

Show code
<div class="thin-choice-row">
  <input class="thin-switch" id="notifications" type="checkbox" role="switch" name="notifications" value="on" checked>
  <label for="notifications">Product notifications</label>
</div>

Each authored example uses the production assets and includes copyable markup.

Standalone switch

A labelled thin-switch host exposes on/off semantics through role=switch.

Show code
<div class="thin-choice-row">
  <input class="thin-switch" id="notifications" type="checkbox" role="switch" name="notifications" value="on" checked>
  <label for="notifications">Product notifications</label>
</div>

Field-composed switch

Compose a switch inside a field with a persistent hint.

Show code
<div class="thin-field">
  <div class="thin-choice-row">
    <input class="thin-switch" id="marketing" type="checkbox" role="switch" name="marketing" value="on">
    <label for="marketing">Marketing updates</label>
  </div>
  <small class="thin-hint">You can change this later in settings.</small>
</div>

Independent switches can share a fieldset when they control related preferences.

Show code
<fieldset class="thin-fieldset">
  <legend>Notifications</legend>
  <div class="thin-choice-row">
    <input class="thin-switch" id="notify-product" type="checkbox" role="switch" name="notify-product" value="on" checked>
    <label for="notify-product">Product updates</label>
  </div>
  <div class="thin-choice-row">
    <input class="thin-switch" id="notify-shipping" type="checkbox" role="switch" name="notify-shipping" value="on">
    <label for="notify-shipping">Shipping alerts</label>
  </div>
</fieldset>

Anatomy

  • Unregistered thin-switch host
  • Native input[type=checkbox] with role=switch
  • Associated label describing what is switched
  • Optional thin-choice-row for control-label alignment

Variants and sizes

  • Standalone switch inside a label — shown above
  • Field-composed switch with hint — shown above
  • Switch inside a fieldset with related toggles — shown above

Rendered fixtures exercise authored content and constrained layouts with the same production assets.

  • Off
  • On (checked)
  • Focused
  • Disabled
  • Forced colors
  • Long localized label
  • Narrow container

Structured state fixtures are not published for this item yet.

Interaction and keyboard behavior

Native checkbox activation with space and click owns the toggle. Role=switch is exposed to assistive technology so the on/off nature is announced.

Accessibility

Provide a visible label that reads sensibly as an on/off action rather than a question. Never depend on color alone; the native indicator and focus outline remain visible. Do not toggle a switch as a side effect of navigation.

Contract
NATIVE
Basis
Prefer a native checkbox. The current role="switch" authoring is an explicit APG Switch promise; its native keyboard, form, and disabled behavior remain the implementation baseline.
Evidence
  • tests/unit/library/choice-controls.test.ts

API

Wrap the native checkbox in unregistered <thin-switch>. Put role=switch, name, value, checked, disabled, and required on the native input. Use .thin-choice-row for horizontal control-label alignment.

Behavior tier: native

Structured host, property, and example tables are not authored for this item yet. Use the summary above and the primary example.

Fallback

Without the switch skin the native checkbox with role=switch still communicates on/off state and submits its value.

Assets and dependencies

  • /components.css

Dependencies: None

Source: packages/ui/src/items/switch/style.ts

Stability evidence

  • Native switch semantics, reduced-motion, forced-colors, and no-JavaScript fixture: test:tests/unit/library/choice-controls.test.ts
  • Complete item-specific API, fallback, and difficult-state documentation: test:tests/unit/library/form-controls-stable.test.ts
  • Cross-theme, density, localized, narrow-container, zoom, and forced-colors fixture: review:site/src/pages/quality/index.astro#quality-review