Form inputs

Switch

<forma-switch>

A checkbox-backed on/off preference control with role=switch and a visible track/thumb treatment.

Authoring tag
<forma-switch>
Category
Form inputs
Behavior owner
Native HTML
Canonical source
patterns/switch.html

Purpose

A switch turns a single setting on or off, and the change is understood to take effect as a setting rather than as an answer to a question. Forma renders it from a native input type="checkbox" with role="switch", so the browser owns checked state, keyboard toggling, form submission and reset. The track and thumb are presentation derived from :checked.

Use when

  • A preference or setting is either on or off, such as notifications, dark mode or auto-save.
  • The user expects the setting to read as a physical toggle in a settings list.
  • The control sits in a list of independent settings where each row can change on its own.

Avoid when

  • The user is answering a yes/no question that can also be unanswered: use Binary choice, which keeps Unanswered distinct from No.
  • The user is agreeing to terms or selecting items from a set: use Checkbox or Multi-choice.
  • Two or more mutually exclusive options are shown: use Segmented control or Choice group.
  • Turning the setting on requires confirmation or an asynchronous permission check before it is legal; present a Button that opens a Dialog instead of a switch that appears to succeed immediately.

Behavior to know

  • The whole label is the touch target; the native input is stretched invisibly over the component.
  • State changes immediately on activation. Motion never delays the checked value.
  • Thumb position (not only color) communicates on versus off, and forced-colors mode uses system Highlight colors.

Basic example

The smallest correct markup: the canonical pattern from patterns/switch.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal switch

Rendered from the canonical pattern file.

Live demo. 1 native action works here and is verified by an outcome test.

HTML · Minimal switch Raw HTML for HTML · Minimal switch
<forma-switch class="forma-component-tag">
<label class="forma-switch" data-forma-motion-weight="standard">
  <input
    class="forma-switch__input"
    type="checkbox"
    role="switch"
    name="notifications"
    value="enabled"
    aria-describedby="notifications-description">
  <span class="forma-switch__track" aria-hidden="true"></span>
  <span class="forma-switch__text">
    <span class="forma-switch__label">Notifications</span>
    <span class="forma-switch__description" id="notifications-description">Receive operational updates.</span>
  </span>
</label>
</forma-switch>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Notification preferences

Independent settings stacked in a fieldset. Each switch carries a label and a description linked with aria-describedby, and one starts checked.

Live demo. 2 native actions work here and are verified by an outcome test.

Notifications
HTML · Notification preferences Raw HTML for HTML · Notification preferences
<forma-switch class="forma-component-tag">
  <fieldset class="forma-stack" data-density="compact">
    <legend>Notifications</legend>
    <label class="forma-switch">
      <input class="forma-switch__input" type="checkbox" role="switch" name="notify-deploys" value="on" checked aria-describedby="notify-deploys-description">
      <span class="forma-switch__track" aria-hidden="true"></span>
      <span class="forma-switch__text">
        <span class="forma-switch__label">Deployment results</span>
        <span class="forma-switch__description" id="notify-deploys-description">Email me when a deployment I started finishes or fails.</span>
      </span>
    </label>
    <label class="forma-switch">
      <input class="forma-switch__input" type="checkbox" role="switch" name="notify-digest" value="on" aria-describedby="notify-digest-description">
      <span class="forma-switch__track" aria-hidden="true"></span>
      <span class="forma-switch__text">
        <span class="forma-switch__label">Weekly digest</span>
        <span class="forma-switch__description" id="notify-digest-description">A Monday summary of activity across all projects.</span>
      </span>
    </label>
  </fieldset>
</forma-switch>

Click or tap the code once to select all of it, then copy.

Scenario

Disabled by policy

A setting the organization has locked. The input is natively disabled, so it is skipped by keyboard focus and excluded from form submission; the description states why, because a dimmed control alone does not explain itself.

HTML · Disabled by policy Raw HTML for HTML · Disabled by policy
<forma-switch class="forma-component-tag">
  <label class="forma-switch">
    <input class="forma-switch__input" type="checkbox" role="switch" name="policy-mfa" value="on" checked disabled aria-describedby="policy-mfa-description">
    <span class="forma-switch__track" aria-hidden="true"></span>
    <span class="forma-switch__text">
      <span class="forma-switch__label">Require two-step sign-in</span>
      <span class="forma-switch__description" id="policy-mfa-description">Locked on by your organization's security policy. Contact an administrator to change it.</span>
    </span>
  </label>
</forma-switch>

Click or tap the code once to select all of it, then copy.

Scenario

Heavy motion weight with a long label

A heavy presentation weight gives the thumb a slower, more settled travel. The long translated label wraps beside the track instead of widening the page. Weight is presentation only and says nothing about importance.

Live demo. 1 native action works here and is verified by an outcome test.

HTML · Heavy motion weight with a long label Raw HTML for HTML · Heavy motion weight with a long label
<forma-switch class="forma-component-tag">
  <label class="forma-switch" data-forma-motion-weight="heavy">
    <input class="forma-switch__input" type="checkbox" role="switch" name="archive-sync" value="on">
    <span class="forma-switch__track" aria-hidden="true"></span>
    <span class="forma-switch__text">
      <span class="forma-switch__label">Synchronisation automatique des archives de projets partagés entre tous les espaces de travail</span>
    </span>
  </label>
</forma-switch>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Mobile settings list

Three switches in a phone-width settings group. The label column absorbs all remaining width, so labels wrap while the 44px-tall rows keep their touch targets.

Live demo. 3 native actions work here and are verified by an outcome test.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • The track keeps its fixed 2.75rem width; the text column takes the remaining width and wraps long labels onto several lines.
  • Each row is at least 44px tall and the entire row, including the label text, toggles the switch on tap.
  • Nothing scrolls horizontally at 320px; descriptions wrap under their labels.
  • Orientation changes only reflow the text column. The control order and semantics do not change.
HTML · Mobile settings list Raw HTML for HTML · Mobile settings list
<forma-switch class="forma-component-tag">
  <fieldset class="forma-stack">
    <legend>Privacy</legend>
    <label class="forma-switch">
      <input class="forma-switch__input" type="checkbox" role="switch" name="mobile-location" value="on" checked>
      <span class="forma-switch__track" aria-hidden="true"></span>
      <span class="forma-switch__text"><span class="forma-switch__label">Share location with my team</span></span>
    </label>
    <label class="forma-switch">
      <input class="forma-switch__input" type="checkbox" role="switch" name="mobile-presence" value="on">
      <span class="forma-switch__track" aria-hidden="true"></span>
      <span class="forma-switch__text">
        <span class="forma-switch__label">Show when I'm active</span>
        <span class="forma-switch__description">Colleagues see a presence dot next to your name.</span>
      </span>
    </label>
    <label class="forma-switch">
      <input class="forma-switch__input" type="checkbox" role="switch" name="mobile-analytics" value="on">
      <span class="forma-switch__track" aria-hidden="true"></span>
      <span class="forma-switch__text"><span class="forma-switch__label">Send anonymous usage analytics</span></span>
    </label>
  </fieldset>
</forma-switch>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Live demo. 1 native action works here and is verified by an outcome test.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
typeinputcheckbox—Required. The switch is a native checkbox; do not substitute a button or div.
roleinputswitch—Required. Announces on/off semantics instead of checked/not checked.
checkedinputbooleanabsent (off)Initial on state. The live state is the input's checked property, owned by the browser.
disabledinputbooleanabsentRemoves the switch from focus order and form submission and dims the row.
nameinputstring—Form field name. Only submitted while the switch is on.
valueinputstring"on"Submitted value when on.
aria-describedbyinputid of .forma-switch__description—Links the supporting description so it is announced after the label.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-switchBlock class—Root label element. It is the grid that places track and text and makes the whole row the hit target.
.forma-switch__descriptionElement class—Optional supporting text referenced by aria-describedby.
.forma-switch__inputElement class—The native checkbox, visually transparent and stretched over the row.
.forma-switch__labelElement class—Visible accessible name.
.forma-switch__textElement class—Wrapper for label and description; it is the column that shrinks and wraps.
.forma-switch__trackElement class—Decorative track; its ::after pseudo-element is the thumb. Mark it aria-hidden="true".
[data-forma-motion-weight]Attribute hook"heavy", "light", "standard"Presentation-only perceived mass for thumb travel: light, standard (default) or heavy. Never encodes importance or risk.
--forma-switch-gapCustom propertydefault 0.1875remInset between track edge and thumb. Default 0.1875rem.
--forma-switch-heightCustom propertydefault 1.5remTrack height. Default 1.5rem.
--forma-switch-thumbCustom propertydefault 1.125remThumb diameter. Default 1.125rem.
--forma-switch-widthCustom propertydefault 2.75remTrack width. Default 2.75rem.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves focus to and from the switch (skipped when disabled).
SpaceToggles the switch. Native checkbox behavior; Enter does not toggle.
Events
EventDescription
input / changeNative events fired by the checkbox when the user toggles it. Listen for change in application code.

Form behavior

Participates as a native checkbox: submits name=value only when on, restores its initial checked attribute on form reset, and supports required.

States

Switch states
StateHow it is expressedPresentation
Offno checked attributeThumb at the inline start, neutral track.
Onchecked / :checkedThumb at the inline end and active track color. Thumb position carries the state without color.
Focus:focus-visible on the inputTwo-tone focus ring drawn around the track, visible on both light and dark surfaces.
Pressed:active on the inputThe thumb scales up slightly while pressed. The hit target does not move.
Disableddisabled attributeRow at reduced opacity with a not-allowed cursor; excluded from focus and submission.

Accessibility

Forma provides

  • Keeps the native checkbox as the focusable, labelled element, so the name, role=switch state and keyboard behavior come from the platform.
  • Wraps the input in its label, so the whole row is the click and touch target.
  • Provides a visible focus indicator on the track and a position-based on/off cue that does not rely on color.
  • Maps the track to system Highlight/Canvas colors in forced-colors mode.

Your application supplies

  • Supply a label that names the setting, not the action ("Weekly digest", not "Turn on").
  • Group related switches in a fieldset with a legend.
  • Explain disabled switches in the description; do not rely on reduced opacity.
  • If toggling triggers an asynchronous effect that can fail, report the outcome with Alert or Toast and restore the checked value on failure.

Responsive behavior

  • Intrinsic sizing: the component is an inline-grid with a fixed track column and a flexible minmax(0, 1fr) text column.
  • Long labels and descriptions wrap inside the text column; the component never forces horizontal page overflow.
  • The row keeps a 44px minimum block size at every width.
  • There are no breakpoints. Placing switches in a Stack or fieldset gives a full-width settings list on phones.

Motion

  • The thumb travels with the shared inertial (spring) model: a short acceleration and a light settle at the end position, communicating that the setting physically changed.
  • data-forma-motion-weight changes perceived mass (light is quicker, heavy is slower and more damped). The checked state itself is immediate.
  • The track color is a perceptual interpolation that is independent of mass.
  • Interrupting a toggle mid-travel re-targets from the current position; the native state is always authoritative.
  • Under prefers-reduced-motion: reduce travel is effectively instant and position still shows the state.

Motion weights

Forma motion is physics-derived: perceived mass changes how a surface accelerates and settles, never what state it is in. Compare the three presentation weights of the same markup:

lightpresentation only
standardpresentation only
heavypresentation only

Usage guidance

Do

  • Apply the setting immediately when toggled, or clearly state when it takes effect.
  • Use positive, noun-phrase labels so on means the named thing is enabled.

Avoid

  • Pairing a switch with a separate Save button; users expect switches to act immediately.
  • Using motion weight to signal that one setting matters more than another.
  • Adding On/Off text that contradicts the screen-reader state; role=switch already announces it.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.