Toggle
A control that allows the user to perform a binary action (on/off).Use the <Toggle /> component for binary actions that occur immediately after the user "flips the switch".
- For confirmation, use a <Checkbox /> component instead of a toggle.
- When error handling is required, use a <Checkbox /> or <Radio /> component instead of a toggle.
- Examples of when to use a <Toggle /> include, but not limited to:
- Enable/disable modules
- Show/hide additional options
- Activate a mode (such as "dark mode") which takes immediate effect
- Turn on/turn off settings
To make the toggle accessible and render valid markup, always provide a concise label that describes what will be switched on/off. The simplest way is using the label prop.
Alternatively, if you need to compose a custom label you can use the ariaLabelledBy prop to make it accessible. Read more on how to do this under Custom label composition.
NOTE: The label prop can not be used at the same time as the ariaLabelledBy prop.
The toggle can be uncontrolled or controlled. Use the toggled prop, along with onClick to take control of the state.
Use the disabled prop when the user shouldn't be able to manipulate the toggle.
There are two toggle sizes, small and medium (default). On smaller screens the toggle's tap (vertical) target area is increased to make the item easier to press.
If you need to compose a custom label you can opt out of using the label prop. Instead, to make it accessible you need to pass in your custom label's id to the toggle's ariaLabelledBy prop. Below is a contrived example of how you can achieve a "clickable toggle card".