Some props/prop values deprecated in SWAN v3.3
Refer to the information on props/prop values provided further down this page. Find more information and migration documentation in the Deprecation roadmap.
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.
Size
size is deprecated in SWAN v3.3
The component now automatically handles sizing based on the selected mode(standardMode/compactMode). Please update your implementation to rely on the new mode-based sizing.
Use size="mini" to reduce the height of a Toggle.
Use size="super" to increase the height of a Toggle.
Hide Text
Use hideText to hide the “On” and “Off” text.
For accessibility support, you are still required to supply both the ToggleSwitchOnLabel and ToggleSwitchOffLabel text. Enabling this option will keep the text accessible to assistive technologies while hiding it only on screens. If the purpose and function of the switch are not obvious without that text, you may need to add visually hidden text to the switch's labelling element to make the purpose of the switch more clear.
Managing state
Pass the defaultActivated prop in order to set the initial state.
If you need to keep track of the state for the ToggleSwitch, use the activated and onRequestActivatedChange props.
onRequestActivatedChange will be triggered with the requested activation state as the first arg and the actual event that triggered the change as the second arg in case you need it.
The preview has been updated.
Accessibility
- The Toggle Switch must have an accessible label that describes it: either an
aria-labelledbyattribute whose value is the id of the element that labels the switch, or anaria-labelattribute with localized text describing the switch. If the page design does not call for a visible label for the switch, you will need to create a labelling element anyway, and then make it visually hidden.
- The "On" and "Off" text will not be presented by screen readers and some assistive technologies. If the purpose and function of the switch are not obvious without that text, you may need to add visually hidden text to the switch's labelling element (see above) to make the purpose of the switch more clear.
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.
| prop | type | required | description | default |
|---|---|---|---|---|
| size | "standard" | "super" | "mini" | null | false | ⚠️ Deprecated - This is deprecated without a replacement.
Size (height) of the toggle.
Available options: 'standard', 'super', 'mini' | standard |
| hideText | boolean | null | false | Whether the on/off text is visually hidden | null |
| activated | boolean | null | false | Whether or not the switch is "activated" aka "on" | null |
| onRequestActivatedChange | ((activated: boolean, event: MouseEvent<HTMLButtonElement, MouseEvent>) => void) | null | false | Callback fired when the ToggleSwitch wants to change its activated state | null |
| defaultActivated | boolean | null | false | The initial activated state.
Ignored if `activated` is provided | null |
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
Was this page useful?
Published: Jan 7, 2022Last updated: Oct 17, 2024
