ButtonToggle

The ButtonToggle is a larger alternative to selection components such as Checkbox, RadioButton, and Switch. It enables users to choose between two states - selected or unselected.

also known as Toggle, Action Button, Toggle Switch

A set of three toggle buttons side by side. The third toggle button is selected.

Usage guidelines

When to use
  • The ButtonToggle should be used when you require a binary component with distinct on/off states
  • To demonstrate that items are actively selected for filtering
When not to use
  • Avoid using the ButtonToggle when a simpler Checkbox, RadioButton, or Switch can be used instead.
  • Do not use ButtonToggle in replacement of a Button, it should only be used for selected and unselected functionality

Best practices

Use clear and concise labels to improve user comprehension

  • To make it clearer, you may want to change the label text to indicate that the ButtonToggle has been selected. For instance, changing "follow" to "Following."
  • Make sure that the ButtonToggle(s) in your application are consistently styled and placed. This should also apply to their sizing, maintaining uniformity throughout the experience.
  • Place the ButtonToggle(s) in a location where users would naturally expect to find them, taking into consideration the context. For instance, position it next to a related feature.
  • If the ButtonToggle(s) trigger a significant action or irreversible change, it is recommended to include a confirmation, such as a toast message.
  • Groups should have 4px spacing between ButtonToggles

Accessibility

The accessibility label for a ButtonToggle uses the label text. Assistive tech (such as a screen reader) will read the UI text followed by the component’s role, which is Switch.

People use Apple’s accessibility features, such as reduced transparency, VoiceOver, and increased text size to personalize how they interact with their device. Supporting these personalizations ensures that everyone has a great user experience. See Apple’s Human Interface Guidelines and documentation about accessibility for iOS:

Accessible design on iOS

, Opens a new tab

Accessible development on iOS
, Opens a new tab

Design tokens

Use these tokens for applying size, weight and color styles to ButtonToggle.


Anatomy

See below how the ButtonToggle component is constructed.


Variants

Size

Example of the large Toggle Button with one selected and the other unselected

Large

Example of the small Toggle Button with one selected and the other unselected

Small

  1. lg (48dp)
    Use when a larger interactive area is required for improved usability
  2. sm (36dp)
    Ideal for situations where a smaller visual footprint is necessary

Images and Graphics

ButtonToggle accepts icons, graphics and full-bleed images. Use these sparingly, to add context to selections.


Example of two Toggle Buttons with an icon to the right of the label

Icons

Example of three Toggle Buttons with graphics above the label

Graphics

Example of three Toggle Buttons with a full-fill image and no label

Full image

  1. Icons
    In situations where a concise visual cue could provide additional information, icons are placed horizontally to the right of the text.
  2. Graphics
    For situations where a higher-fidelity visual cue enhances comprehension, for example, selecting hair patterns. Graphics sit vertically above the text and the buttons will grow to accommodate their graphics. Large is the smallest height size.
  3. Full images
    Use when a larger visual element is required, for example skin color selection. Full image ButtonToggles grow to accommodate their graphics. Images fill the container and Large is the smallest height size.

Save

Save variant features our brand red and is only used for “Save” functionality, however it functions the same as all other ButtonToggles.

Example of two Save ToggleButtons, one selected, one unselected

States

Example of three Toggle Buttons, all in a selected state

Selected

Example of three Toggle Buttons, all in an unselected state

Unselected

  1. Selected
    The selected state refers to when the ButtonToggle is activated or toggled on. In this state, the outline will appear black and be 2px in size.
  2. Unselected
    The unselected state refers to when the ButtonToggle is deactivated or toggled off. For default ButtonToggles, the outline appears gray and is 1dp. For full images and Save variants, there is no border.

Writing

  • Use fewer than three words, ideally only one.
  • Use clear and concise copy for labels, tooltips, and any supporting text.
  • To make it clearer, you may want to change the label text to indicate that the ButtonToggle has been selected. For instance, changing "follow" to "Following."
  • Make sure that all text is easy to translate for localization purposes.

For writing best practices, refer to the content standards documentation.

Localization

For RTL (right-to-left) languages, the layout of the ButtonToggle is mirrored.

Edit page on GitHub