ToggleSwitch

ToggleSwitch is used to immediately toggle a setting on or off.

Page navigation navigation

Anatomy

Diagram of ToggleSwitch with its parts labeled

Track: Clickable area the knob moves within. Changes color to show on/off state.
Knob: Moves to show on/off state.
Status: Label showing on/off state.

Label and caption

Each ToggleSwitch needs a concise label describing the action (e.g., "Discussions" or "Automatically watch repositories"). Avoid state-descriptive labels.

Optionally, you may include a caption about the setting that is being turned on or off.

Use succinct phrases with verbs or nouns

Don’t

Layout

By default, lay out a ToggleSwitch horizontally justified with its label and optional description.

You may use a vertical layout when a ToggleSwitch is layed out inline with other content, or if a horizontal layout would put the switch too far from its label. If the vertical layout is left-aligned, the "on"/"off" text may be moved to the right of the switch.

Progressive disclosure

The progressive disclosure pattern may be used to hide or show content based on whether a ToggleSwitch is on. Content revealed on ToggleSwitch activation should always come after the ToggleSwitch.

Mixed values

Avoid using a ToggleSwitch for mixed values. For groups with configurable options, use a button to toggle the section, remembering individual states.

Configuration options section that can be enabled or disabled. Configuration controls are hidden when it is disabled.

Use a button to affect multiple related toggles

Don’t

ToggleSwitch vs checkbox

ToggleSwitches act as instant-save controls for boolean settings, while checkboxes are for selections requiring explicit save actions.

A ToggleSwitch should never be used as a replacement for a checkbox. See saving patterns for more details.

Don’t