Usage
- Use a toggle for binary controls like on/off or enabled/disabled.
- Use when the action is performed immediately and doesn't require confirmation or form submission.
- A toggle is 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.
- Use for a two-step action: selection and execution
- Use if another action is required to execute the choice, use a checkbox
Examples
- Enhanced Tracking Protection Panel
- Add-ons manager
Design properties
See Storybook for code
| Property | Values | Default |
|---|---|---|
| State Variant | Default | Hover | Active | Focus | Disabled | Default |
| Checked Variant | Off | On | Off |
| Property | Values | Default |
|---|---|---|
| Icon InstanceSwap | ||
| Show slot Boolean | true | false | false |
| Slot InstanceSwap | ||
| Show icon Boolean | true | false | true |
| Disabled Variant | Off | On | Off |
| Show description Variant | Off | On | Off |
| Show support link Variant | Off | On | Off |
Types
Toggle 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.
With label
With label and description
With label and icon
With label and link
Writing guidelines
- 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.
- 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.
- Use terminal punctuation after toggle labels.
Changelog
|
Date |
Version |
Notes |
|---|---|---|
|
Aug 4, 2025 |
2.0.0 |
Simplified template |
|
Nov 30, 2023 |
1.0.0 |
Initial draft of toggle guidance |