<iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5HGSQD2L" height="0" width="0" style="display:none;visibility:hidden" title="GTM"></iframe>

Toggle Switch

A choice between two mutually exclusive options.
scriptKeys: toggleSwitchstyleKeys: toggleSwitch

Use Toggle Switch...

  • To prompt users to choose between two mutually exclusive options that always have a default value, like "on" or "off".
  • When immediately activating or deactivating the selected choice or setting.

Don't use Toggle Switch...

  • If you need to display an indeterminate value. A Toggle Switch is either "on" or "off". Use Checkbox instead.
  • To select more than one option. Use Checkbox instead.
  • To apply a setting that needs to be confirmed and reviewed by the user before they are submitted. Use Checkbox instead.
  • To select one option from a list of options. Use Radio Button instead.

The preview has been updated.

Size

Use size="mini" to reduce the height of a Toggle.

The preview has been updated.

Use size="super" to increase the height of a Toggle.

The preview has been updated.

Hide Text

Use hideText to hide the “On” and “Off” text.

The preview has been updated.

Disabled

Use disabled when the toggle option is permanently set or is dependent on a prior user action. Use a message to explain why the option cannot be toggled.

The preview has been updated.

Managing state

Pass the defaultActivated prop in order to set the initial state.

The preview has been updated.

Accessibility

The ToggleSwitch component needs an accessible name that describes what the switch controls. The name will be applied to its underlying button element and used by assistive technologies to describe it to its users. This is separate from the ToggleSwitchOnLabel/ToggleSwitchOffLabel and cannot change based on the switch state.

If visible text already exists that summarizes its purpose, update the ToggleSwitch component with an aria-labelledby attribute whose value is the id of the element containing that text.

If no visible text exists that summarizes its purpose, create a visually hidden element with descriptive text, then use aria-labelledby accordingly.

If you don't have access to the id on the labelling element, update the ToggleSwitch component with an aria-label attribute whose value is that descriptive text.

Remember that all text (visible or hidden) must be localized since it will be read to the user!

The preview has been updated.

Content

  • Provide concise, explicit labels.
  • Describe the option that the switch controls.
  • Provide an explanatory error message.

References

NN/g toggle switch guidelines

Props

ToggleSwitch
This component is implemented using the <button /> as the root element. You can utilize the native attributes supported by <button /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
proptyperequireddefault
aria-label
Defines a string value that labels the current element. Provides a localized accessible label which describes what the Toggle Switch's purpose is. Prefer `aria-labelledby` over this and use it when you don't have access to the `id` of the labeling element. This is separate from the ToggleSwitchOnLabel/ToggleSwitchOffLabel and cannot change based on the switch state. e.g. "Include VAT" @see aria-labelledby.
stringfalse
null
aria-labelledby
Identifies the element (or elements) that labels the current element. ID of an element whose text content labels the Toggle Switch. The referenced element's text should be localized. e.g. id of element with text "Include VAT" @see aria-describedby.
stringfalse
null
size
Size (height) of the toggle.
⚠️ Deprecated - This is deprecated without a replacement.
"standard" | "mini" | "super" | nullfalse
standard
hideText
Whether the on/off text is visually hidden
boolean | nullfalse
false
activated
Whether or not the switch is "activated" aka "on"
boolean | nullfalse
null
onRequestActivatedChange
Callback fired when the ToggleSwitch wants to change its activated state
((activated: boolean, event: MouseEvent<HTMLButtonElement, MouseEvent>) => void) | nullfalse
null
defaultActivated
The initial activated state. Ignored if `activated` is provided
boolean | nullfalse
false
ToggleSwitchOffLabel
This component is implemented using the <span /> as the root element. You can utilize the native attributes supported by <span /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.
ToggleSwitchOnLabel
This component is implemented using the <span /> as the root element. You can utilize the native attributes supported by <span /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.
See core props for additional props that can be applied to this component.

Related