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.
Minimal switch
Rendered from the canonical pattern file.
Live demo. 1 native action works here and is verified by an outcome test.
<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
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.
<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.
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.
<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.
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.
<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 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.
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.
<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.
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.
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.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
type | input | checkbox | — | Required. The switch is a native checkbox; do not substitute a button or div. |
role | input | switch | — | Required. Announces on/off semantics instead of checked/not checked. |
checked | input | boolean | absent (off) | Initial on state. The live state is the input's checked property, owned by the browser. |
disabled | input | boolean | absent | Removes the switch from focus order and form submission and dims the row. |
name | input | string | — | Form field name. Only submitted while the switch is on. |
value | input | string | "on" | Submitted value when on. |
aria-describedby | input | id of .forma-switch__description | — | Links the supporting description so it is announced after the label. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-switch | Block class | — | Root label element. It is the grid that places track and text and makes the whole row the hit target. |
.forma-switch__description | Element class | — | Optional supporting text referenced by aria-describedby. |
.forma-switch__input | Element class | — | The native checkbox, visually transparent and stretched over the row. |
.forma-switch__label | Element class | — | Visible accessible name. |
.forma-switch__text | Element class | — | Wrapper for label and description; it is the column that shrinks and wraps. |
.forma-switch__track | Element 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-gap | Custom property | default 0.1875rem | Inset between track edge and thumb. Default 0.1875rem. |
--forma-switch-height | Custom property | default 1.5rem | Track height. Default 1.5rem. |
--forma-switch-thumb | Custom property | default 1.125rem | Thumb diameter. Default 1.125rem. |
--forma-switch-width | Custom property | default 2.75rem | Track width. Default 2.75rem. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves focus to and from the switch (skipped when disabled). |
| Space | Toggles the switch. Native checkbox behavior; Enter does not toggle. |
| Event | Description |
|---|---|
input / change | Native 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
| State | How it is expressed | Presentation |
|---|---|---|
| Off | no checked attribute | Thumb at the inline start, neutral track. |
| On | checked / :checked | Thumb at the inline end and active track color. Thumb position carries the state without color. |
| Focus | :focus-visible on the input | Two-tone focus ring drawn around the track, visible on both light and dark surfaces. |
| Pressed | :active on the input | The thumb scales up slightly while pressed. The hit target does not move. |
| Disabled | disabled attribute | Row 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-weightchanges 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: reducetravel 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:
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.