Toggle

Examples

View in Pajamas UI Kit →

Structure

1. Label: Describes the control when the toggle is on.
2. Description: (optional) Provides more context for the label.
3. Switch: Visual indication of whether the toggle is on or off.
4. Body: Containing body for the switch to move on and off.
5. Help text: Clarifies the outcome of changing the toggle state.

Guidelines

When to use

• There's a binary choice for enabling a setting (ux-research#1215). For examples, choices that follow a boolean relationship like on/off, true/false, enable/disable, or activate/deactivate.
• The item being toggled has a default state. For example, notifications default to off for a merge request you haven't participated in.
• The result of changing the toggle state is immediately effective and there's no need for an additional action to apply or save a change.

When not to use

• A submit button is needed to apply or save a selection.
• When the setting exists within a form that has other elements, like text inputs or checkboxes, that need to be saved or submitted.
• Two choices don't map to a boolean relationship like on/off.
• There are more than two choices.
• If multiple items can be selected, including nested items, and the result of the selection has to be saved or submitted, consider using a checkbox instead.
• If only one item can be selected and the result of the selection has to be saved or submitted, consider using a radio button instead.
• If making a selection from a list of items, consider using a combobox instead.
• If changing a content view or preference in the context of that content, consider using a segmented control instead.

Appearance

• Toggle labels are set in bold, positioned above the element by default.
• The label can be positioned to the left if only a single toggle is being used.
• The description sits below the label.

Behavior

• Consider providing feedback of the toggle state change by using a toast.

Content

Label

• Concisely describe what the control does when the toggle is on.

Description

• Optional: Provides more context for the label.
• Only available using a vertical layout.

Help text

• Clarifies the outcome of changing the toggle state.
• Only available using a vertical layout.

Accessibility

• The gl-toggle component requires an id, which is used in the aria-labeledby attribute value.
• Use aria-describedby to associate the description and help text with the toggle for a screen reader user.