Skip to content

Toggle

A toggle is a switch control that lets users turn a setting on or off.

Quarantine

DesignDevelopAccessibility

A toggle is a switch control that flips a single setting between two opposing states — on or off — and applies the change immediately. Reach for one when the setting is binary and takes effect the moment it is switched, the way you’d expect a physical light switch to behave. Built on a native <input type="checkbox">, it pairs a sliding thumb with a clear text label so the state reads at a glance.

Anatomy

Section titled “Anatomy”
  1. Switch
  2. Label

The Switch is a single native control that renders the whole toggle: the pill-shaped track carries the on / off colour, the thumb slides from one end to the other, and an icon inside the thumb — a cross when off, a check when on — repeats the state without relying on colour. The Label names the setting the switch controls.

When to use it

Section titled “When to use it”

Use a Toggle when:

  • A single setting flips between two opposing states (on / off, enabled / disabled).
  • The change takes effect immediately, with no separate Save or Submit step.
  • The control adjusts a system or preference setting — notifications, dark mode, Wi-Fi.

Avoid a Toggle when:

  • The user picks from a list of non-exclusive options — that’s a Checkbox.
  • The choice only applies after submitting a form — a Checkbox reads as “pending” in a way a switch does not.
  • More than two states are possible, or the action needs confirmation before it takes effect.

Properties

Section titled “Properties”

Track

The pill-shaped background rendered on the native input. It carries the visible on / off state — the neutral emphasis fill when on, a muted fill when off — and mutes to a subtle fill when disabled. The change of colour is never the only cue; it always moves with the thumb.

Thumb

The circular knob that slides across the track. Its position — leading edge for off, trailing edge for on — is the primary, colour-independent signal of the state, so it survives for colour-blind users and in high-contrast modes.

Icon

Sits inside the thumb and repeats the state a third time: a cross when off, a check when on. Decorative — the on / off value is conveyed semantically by the native <input type="checkbox">, not the icon.

State

Rested, Hover, Pressed, Disabled, and Focus, plus an Error treatment via .is-error. Hover and Pressed add a soft outline around the thumb; Focus shows the global focus ring; Disabled mutes the track and drops the control from the tab order. Each state is driven by its own design-token set so it adapts across schemes.

Size

Two sizes — Small and Large. Large is the default for forms and settings; Small is reserved for dense layouts. The label and its clickable region keep the interactive target comfortable in both sizes.

Platform considerations

Section titled “Platform considerations”

Desktop

Mouse and keyboard both work — the switch is a single tab stop, toggled with Space. Align the switch with its label on the leading edge and keep the pair on one line so the relationship is obvious.

Tablet

Touch and pointer both apply. Keep the label’s clickable area extended to the full row so a tap anywhere on the line flips the switch without having to hit the thumb precisely.

Mobile

Touch-first. The thumb and its label stay large enough to hit comfortably (≥ 44 px tall). Stack toggles vertically in a settings list; never crowd two switches side by side at narrow widths.

Best practices

Section titled “Best practices”

A toggle promises an instant result — make the label describe the setting, and let the switch position and icon, not colour alone, tell the state.

Do

Use a toggle only for binary settings that apply immediately. Label it with the setting it controls (“Notifications”), phrased so “on” is the affirmative. Keep the label visible and next to the switch. Let the thumb position and icon carry the state alongside colour, and show the focus ring on keyboard focus.

Don't

Don’t use a toggle when the change only takes effect after a Save step — that implies a pending state a switch doesn’t have. Don’t use one to pick among a list (that’s a Checkbox) or when only one of several options can be chosen (that’s a Radio). Don’t rely on the track colour alone to signal the state, and don’t replace the visible label with an icon-only control.

Content guidelines

Section titled “Content guidelines”

Label the toggle with the setting it controls, not the action it performs — “Notifications” or “Dark mode”, never “Turn on notifications”. Phrase it so the “on” position is the affirmative, matching the switch’s meaning, and use sentence case (“Auto-play videos”). Keep the label short and self-describing; if the setting needs a caveat, put it in supporting text beneath the switch rather than lengthening the label.