Toggle/Switch

null

Definition

Toggles are a form input that switches between two states, typically on/off or enabled/disabled.

Anatomy

Defining shared language for discussing the construction and structure of this component.

null

Key

Category

Parts

1

Text, Label

Font family, size/line height, color

2

Shape, Thumb

Background color, border radius

3

Shape, Track

Border radius, border color

4

Shape, Track

Background color, padding (block [top, bottom], inline [left, right])

5

Text, Description

Font family, size/line height, color

Usage

Figma library (internal only)

Storybook Documentation

Think of a toggle like a switch. If it would be appropriate to use a switch in the physical world for this action, it is likely appropriate to use a toggle in software.

Toggles may be used inside other components.

Examples

  • Use for simple binary controls like on/off or enabled/disabled
  • Use for a two-step action: selection and execution
  • Use if another action is required to execute the choice, use a checkbox

Variants

Figma library (internal only)

HCM library (internal only)

Acorn offers 4 toggle variants in 1 size, with 5 states across 3 modes (themes).

Sizes

States

A toggle can be on or off, this is a binary switch state applied to the overall component. In addition, toggles have 5 interactive states that affect the visual output.

Available interactive states: Default, hover, active, focus, and disabled

The focus and disabled states have important caveats that apply across modes.

Focus

:focus states are used both for keyboard navigation and when a user focuses using a mouse. They are vital for accessibility and may not be omitted.

The CSS pseudo class :focus does not affect visual output in iOS or Android.

Disabled

Disabled visual styles should only be applied when a toggle is disabled.

Disabled toggles are unusable. Disable a toggle to keep users from interacting with the toggle until conditions are met.

Toggle only

Figma component (internal only)

This is a variant of the toggle for use when labels cannot be shown. You should always get approval for using this variant. Unlabeled toggles aren’t typically considered accessible or usable.

Examples

null
null

High contrast mode has different themes. The examples shown below are from Windows 11.

Desert theme

null

Night Sky theme

null

With description

Figma component (internal only)

null
null

High contrast mode has different themes. The examples shown below are from Windows 11.

Desert theme

null

Night Sky theme

null

With label

Figma component (internal only)

null
null

High contrast mode has different themes. The examples shown below are from Windows 11.

Desert theme

null

Night Sky theme

null

Storybook documentation

null
null

High contrast mode has different themes. The examples shown below are from Windows 11.

Desert theme

null

Night Sky theme

null

Behavior and interaction

Toggles are an interactive element with a binary switch state: on or off.

When a user clicks a toggle the switch state changes from current to opposite. I.e. clicking an off toggle changes it to an on toggle.

The switch state change is animated and involves a color change.

Writing guidelines

Due to such limited space, keep label strings to 1-2 words and use a tooltip if you need to provide additional details.

The toggle itself already implies a binary “on” / “off” action, so labels should align with that action. The following best practices apply to copy for toggles:

  • Stay concise, keep labels to 1-2 words
  • Labels should indicate the name of the feature, with the understanding that it turns on and off (Unless there is particular confusion, the label shouldn’t need an action verb).
  • Tooltips should include action verbs that indicate the change that will happen when toggled.

Localization

To pressure test designs, use tools like Google Translate or Transvision to see how design reacts to Chinese, English, and German.

Not sure? Check with #l10n in Slack.

Accessibility

All toggles should include tooltip text.

Since a toggle is an interactive control, it must be focusable and keyboard accessible. The expected keyboard shortcut for toggling the value of a switch is the Space key.

Read more here:

Need guidance? Check with #accessibility in Slack.

Changelog

Date

Version

Notes

Nov 30, 2023

0.1.0

Initial draft of toggle guidance.

Status checklist

All States

Includes all applicable states (hover, focus, disabled, etc...)

All Themes

Works properly across all themes (theme name, theme name, etc...)

All Modes

Works properly across all modes (light, dark, high contrast)

All Desktop Environments

Works properly across all environments (Windows, MacOS, Linux)

All Mobile Environments

Works properly across all environments (iOS, Android)

Overall Accessibility

Has been tested and reviewed by A11y Team.

Color / Accessibility

All color has been tested against and passed all the latest WCAG 2.1 A & AA standards.

Text / Accessibility

All text has been tested against and passed all the latest WCAG 2.1 A & AA standards.

Contrast / Accessibility

All contrast has been tested against and passed all the latest WCAG 2.1 A & AA standards.

Interaction / Accessibility

All interactions have been tested against and passed all the latest WCAG 2.1 A & AA standards.

Content Design Review

Has been tested and reviewed by Content Design Team.

Writing Guidelines

Follows guidance for writing and language use.

Localization

Works properly across locales, and includes guidance for RTL languages.

Defined Behavior

Guidance for behavior when interacted with.

Defined Interactions

Guidance for interaction capabilities, ie. keyboard interactions.

Usage Guidelines

Includes guidance for usage, dos and don'ts, best practices.

Tokens

All attributes are available as tokens.

Figma Library

Has a reusable Figma component.

Storybook

Is documented in Storybook.

Code

Has a code counterpart.