ARIA Switch Button
Similar to a toggle button or checkbox, a switch button is meant to be used when its visual appearance most resembles an "on and off" "switch".
The expected user experience of a switch button is for an immediate action to take place. For instance, toggling a light/dark theme for a site or application, where the theme change instantly takes effect.
In contrast, when interacting with a checkbox, any change in UI state is typically expected to occur after a purposeful form submission by the user. See related WCAG success criteria "on input".
A toggle button and switch may seem similar in functionality and purpose, but their differences become more apparent if you focus on the semantics, typical visual treatments, and announcements of each.
In browsers and screen readers that support both elements, a toggle button is typically announced as "pressed" in its active state, where a switch is announced as "on". A toggle button may be grouped within a series of toggle buttons, where activating one may deactivate another. A switch ideally is an independent UI component, and should not be modified by outside controls.
For more information about the Switch Role, and its differences to toggle buttons and checkboxes, please visit:
- Switch Role Accessible Rich Internet Applications (WAI-ARIA) 1.1, Specification
- Inclusive Components: Toggle Button Article
How does it work?
The baseline for this component requires the following markup:
<button type="button" data-action="aria-switch" role="switch" aria-checked="false" aria-labelledby="ID_HERE" disabled> <!-- Meaningful label here --> </button>
data-action="aria-switch" is required for the switch component to work. All setup and functionality is based around this attribute.
disabled attribute will be removed from the switch, unless a
data-keep-disabled attribute is present.
aria-checked attribute should be set to announce the current state of the switch. If this attribute is not present, the script will default to setting an
aria-labelledby to point to a text label that this switch will control the state of. If a visible label is not present (e.g. you're using an icon of some sort, or somehow it's visually apparent what this switch does without a visible label), be sure to use an
aria-label instead to give context as to what this switch is toggling on/off.
Currently there is no fall back for setting an appropriate label or labelledby value to this component, if one is not manually set. Instead a console error is purposefully left in the script to alert developers of this failure for when a switch is missing these attributes.
Screen Reader Quirks
Note that since 2017, and tested again with VoiceOver on iOS 11.3 & 11.4, VoiceOver continues to have issues with
role="switch" elements. VoiceOver will fall back to announcing switches as checkboxes, but with bugged behavior, where the state is not announced.
JAWS 2018 + IE11 also experience issues with switches.
NVDA 2018.2.1 + FireFox and Chrome will announce elements with
role="switch" as "not pressed" and then announce whether they are checked or not. It doesn't matter the current state of whether the switch is checked or not, it will always announce "not pressed." This can be incredibly confusing to determine the actual state of these elements since both checked and pressed states are announced.
Depending on your audience and the devices / browsers they use, you may want to use caution before fully embracing switches without suitable fall backs.
License & Such
This script was written by Scott O'Hara.
It has an MIT license.
Do with it what you will :)