Toggle
Toggle lets users choose between two states or options.
Examples
Usage
Do
- Use for mutually exclusive options (e.g. on and off) where changes become effective immediately
- Provide a label that clearly describes the property being changed
- Perform toggle changes instantly or inform the user changes have been saved
- Use a toggle consistently across the interface for the same action
Don’t
- Use when the user needs to take extra steps for the change to take effect (e.g. clicking a submit button)
Anatomy
- (1) Toggle off
- (2) Toggle on
- (3) Disabled toggle off
- (4) Disabled toggle on
- (5) Focused toggle off
- (6) Focused toggle on
Space and sizing
Default toggle and label: The space reserved for the on/off labels doesn't change when the toggle state changes.
Related
APIs
IToggleProps
ariaDescribedBy
string
aria-describedby id to use for the component
ariaLabel
string
Aria Label for the Toggle for screen reader users.
checkedfalse
IReadonlyObservableValue<boolean> | boolean
The checked state of the toggle.
className
string
Optional class name to add to the toggle element.
disabled
boolean
If true, the toggle cannot be interacted with.
excludeFocusZone
boolean
Set to true if you don't want the toggle's focus managed by a FocusZone.
excludeTabStop
boolean
Set to true to omit setting the tab index to 0.
id
string
Optional id to add to the toggle element.
offAriaLabel
string
Aria label when checked is false.
offText
string
Text to display when the toggle is unchecked.
onAriaLabel
string
Aria label when checked is true.
onChange
(event: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>, checked: boolean) => void
An optional callback to handle click and keyboard events.
onText
string
Text to display when toggle is checked.
roleswitch
string
Aria role of the toggle element.
text
string
Text to display next to the toggle regardless of checked state.