Toggle

OverviewCopy Anchor Link

A toggle switch represents a binary on/off, active/inactive, show/hide state. If the setting has more than two states, or requires the user to pick from a list of options, use a different control (radio buttons, select, segmented control).

When to useCopy Anchor Link

Instant effect:
A toggle change should apply immediately — the user should never need to click Save or Submit to confirm it. Exceptions:

• Inside a desktop dialog: if flipping the switch reveals more complex settings, it's okay for the whole change to apply together with the dialog's own "Save" or "Submit" — instead of taking effect the instant it's flipped
• Big or hard-to-undo changes: if flipping it does something serious (like turning off two-factor authentication), still use a switch — just ask for confirmation first, rather than applying it silently

Dependent behavior:
Show or hide a set of dependent settings tied to that state: Hide dependent settings when the toggle is off, and reveal them again when it's on — but preserve and save their values while hidden. Show/hide with the toggle explicitly if there isn't enough space to show all dependent settings at once, or when the UI overloads.

Toggle vs Checkbox:
A switch and a checkbox both represent a binary on/off state, but they carry different promises to the user: flipping a switch takes effect the instant it's flipped, while a checkbox is understood to be staged until the surrounding form is submitted.

AnatomyCopy Anchor Link

A switch is a compound component: an outer track (.nm-switch), a visually-hidden native <input type="checkbox"> (.nm-switch__input) that carries all real interaction and focus, and a visible thumb (.nm-switch__thumb) that slides between the two ends of the track. The thumb's own ::after renders a small checkmark (or dash, when indeterminate) once it reaches the "on" position.

Tokens and values that drive each partCopy Anchor Link

Selection statesCopy Anchor Link

Like checkbox, a switch supports a middle (indeterminate) state for summarizing a group of settings that aren't all in the same position. Unlike checkbox, this is a class on the outer track (.is-indeterminate) rather than a native DOM property, since the visible thumb position (centered) isn't something the native indeterminate property drives on its own here.

Switch is fixed at 48×24px (track) / 20×20px (thumb) — there are no size modifiers.

Interaction statesCopy Anchor Link

Hover targets the whole track, not just the thumb — this matches the larger click/tap target real switches have.

All shown in the "on" position

No disabled stateCopy Anchor Link

Switches never ship the native "greyed out" disabled look. If a setting is off the table for now, use read-only so its current position stays legible and its value still submits with the form.

Read-only implementationCopy Anchor Link

Put .is-readonly on the outer .nm-switch track (that's what the CSS targets) and tabindex="-1" / aria-readonly="true" on the inner .nm-switch__input, since that's the real focusable element:

<span class="nm-switch is-readonly">
  <input type="checkbox" class="nm-switch__input" checked tabindex="-1" aria-readonly="true">
  <span class="nm-switch__thumb"></span>
</span>

MarkupCopy Anchor Link

Pair with .nm-choice-field the same way as checkbox and radio. Write the label as the setting's name in its current framing, not as a question or an instruction to act.

Light & dark themeCopy Anchor Link

Both previews are locked — they don't follow the page theme switcher.

Do & don'tCopy Anchor Link

AccessibilityCopy Anchor Link

SemanticsCopy Anchor Link

• The underlying element is <input type="checkbox">. Add role="switch" on the input so assistive tech announces it as a switch rather than a generic checkbox, and mirror its state with aria-checked.
• Wrap it in .nm-choice-field's <label> so the visible text is the accessible name.

Middle stateCopy Anchor Link

• Set .is-indeterminate on the outer .nm-switch (not a native property here). Also set aria-checked="mixed" on the inner input so screen readers announce it correctly.

Read-onlyCopy Anchor Link

• Put .is-readonly on the outer .nm-switch and tabindex="-1" / aria-readonly="true" on the inner .nm-switch__input — the real focusable element. This removes it from the tab order while keeping its value in the form.

KeyboardCopy Anchor Link

• Tab moves focus to the hidden <input>; Space toggles it.
• Focus uses :focus-visible on the input, but the ring should visually wrap the track — verify it renders around the full .nm-switch, not just the invisible input, when you implement it.

PlaygroundCopy Anchor Link

Token referenceCopy Anchor Link

ImplementationCopy Anchor Link

The visible track and thumb are decorative; the real interactive element is the hidden checkbox input. No JavaScript is required for basic on/off — only for the middle state, which has no native equivalent.

<link rel="stylesheet" href="namirial-theme.css">

<label class="nm-choice-field">
  <span class="nm-switch">
    <input type="checkbox" class="nm-switch__input" role="switch">
    <span class="nm-switch__thumb"></span>
  </span>
  <span class="nm-choice-field__label">Dark mode</span>
</label>

CSS classesCopy Anchor Link