Skip to content

Toggle

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

  • CSS

Maintained by Platform

Ready to use

DesignCSSAccessibility

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

The switch itself is one fixed size, in every state and on every surface — sizing it down would put the thumb below a comfortable target. What the Small and Large variants change is the label: Large (the default, for forms and settings) sets it on the body-6 type scale, Small drops it to body-7 for dense layouts. The switch is identical in both.

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 switch is a small target on its own, so let the label carry the rest of it — the label is wired to the input, which means a tap anywhere on the text flips the switch. Give each row enough height that the two together stay comfortable to hit. 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.