ARIA: switch role
The ARIA switch
role is functionally identical to the checkbox role, except that instead of representing "checked" and "unchecked" states, which are fairly generic in meaning, the switch
role represents the states "on" and "off."
This example creates a widget and assigns the ARIA switch
role to it.
<button
type="button"
role="switch"
aria-checked="true"
id="speakerPower"
class="switch">
<span aria-hidden="true">off</span>
<span aria-hidden="true">on</span>
</button>
<label for="speakerPower" class="switch">Speaker power</label>
Description
The ARIA switch
role is identical to the checkbox role, except instead of being "checked" or "unchecked", it is either "on" or "off". Like the checkbox role, the aria-checked
attribute is required. The two possible values are true
and false
. Unlike an <input type="checkbox">
or role="checkbox"
, there is no indeterminate
or mixed
state. The switch
role does not support the value mixed
for the aria-checked
attribute; assigning a value of mixed
to a switch
instead sets the value to false
.
Assistive technologies may choose to represent switch
widgets with a specialized presentation to reflect the notion of an on/off switch.
Since a switch is an interactive control, it must be focusable and keyboard accessible. If the role is applied to a non-focusable element, use the tabindex
attribute to change this. The expected keyboard shortcut for toggling the value of a switch is the Space key. The developer is required to change the value of the aria-checked
attribute dynamically when the switch is toggled.
All descendants are presentational
There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a switch
. To deal with this limitation, browsers, automatically apply role presentation
to all descendant elements of any switch
element as it is a role that does not support semantic children.
For example, consider the following switch
element, which contains a heading.
<div role="switch"><h3>Title of my switch</h3></div>
Because descendants of switch
are presentational, the following code is equivalent:
<div role="switch"><h3 role="presentation">Title of my switch</h3></div>
From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the accessibility tree:
<div role="switch">Title of my switch</div>
Associated ARIA roles, states, and properties
aria-checked
attribute-
The
aria-checked
attribute is required when using theswitch
role, as it represents the current state of the widget that theswitch
role is applied to. A value oftrue
represents the "on" state;false
represents the "off" state; a value ofmixed
is not supported by the switch role, and is treated asfalse
. aria-readonly
attribute-
The
aria-readonly
attribute is supported by theswitch
role. It indicates whether the widget's state is editable by the user. A value offalse
means that the user can change the widget's state; a value oftrue
means that the user cannot change the widget's state. The default value isfalse
.
Required JavaScript features
- Handler for click events
-
When the user clicks on the switch widget, a click event is fired, which must be handled in order to change the state of the widget.
- Changing the
aria-checked
attribute -
When a click event is fired on the switch widget, the handler must change the value of the
aria-checked
attribute fromtrue
tofalse
, or vice versa.
Possible effects on user agents and assistive technology
When the switch
role is added to an element, the user agent handles it like this:
- The element is exposed to the system's accessibility infrastructure as having the
switch
role. - When the
aria-checked
attribute's value changes, an accessible event is fired using the system's accessibility API if one is available and it supports theswitch
role. - All elements that are descendants of an element with the
switch
role applied to it are automatically assigned rolepresentation
. This prevents elements that are used to construct the switch from being interacted with individually by assistive technologies. Text in these elements remains visible to the user agent and may be read or otherwise delivered to the user, unless it's expressly hidden usingdisplay: none
oraria-hidden="true"
.
The assistive technology, if it supports the switch
role, responds by doing the following:
- Screen readers should announce the element as a switch, optionally providing instructions as to how to activate the switch.
Note: There are varying opinions on how assistive technologies should handle this role; the above is a suggested practice and may differ from other sources.
Examples
The following examples should help you understand how to apply and use the switch
role.
Adding the switch role in ARIA
This simple example just creates a widget and assigns the ARIA switch
role to it. The button is styled with an appearance reminiscent of an on/off power switch.
HTML
The HTML is fairly simple here. The switch is implemented as a <button>
element which is initially checked courtesy of its aria-checked
attribute being set to "true"
. The switch has two child elements containing the "off" and "on" labels and is followed by a <label>
identifying the switch.
<button role="switch" aria-checked="true" id="speakerPower" class="switch">
<span>off</span>
<span>on</span>
</button>
<label for="speakerPower" class="switch">Speaker power</label>
JavaScript
This JavaScript code defines and applies a function to handle click events on switch widgets. The function changes the aria-checked
attribute from true
to false
, or vice versa.
document.querySelectorAll(".switch").forEach((theSwitch) => {
theSwitch.addEventListener("click", handleClickEvent, false);
});
function handleClickEvent(evt) {
const el = evt.target;
if (el.getAttribute("aria-checked") === "true") {
el.setAttribute("aria-checked", "false");
} else {
el.setAttribute("aria-checked", "true");
}
}
CSS
The purpose of the CSS is to establish a look and feel for the switch that's reminiscent of the power switch paradigm.
button.switch {
margin: 0;
padding: 0;
width: 70px;
height: 26px;
border: 2px solid black;
display: inline-block;
margin-right: 0.25em;
line-height: 20px;
vertical-align: middle;
text-align: center;
font:
12px "Open Sans",
"Arial",
serif;
}
button.switch span {
padding: 0 4px;
pointer-events: none;
}
[role="switch"][aria-checked="false"] :first-child,
[role="switch"][aria-checked="true"] :last-child {
background: #262;
color: #eef;
}
[role="switch"][aria-checked="false"] :last-child,
[role="switch"][aria-checked="true"] :first-child {
color: #bbd;
}
label.switch {
font:
16px "Open Sans",
"Arial",
sans-serif;
line-height: 20px;
vertical-align: middle;
user-select: none;
}
The most interesting part is probably the use of attribute selectors and the :first-child
and :last-child
pseudo-classes to do all the heavy lifting of changing the appearance of the switch based on whether it's on or off.
Result
The result looks like this:
Specifications
Specification |
---|
Accessible Rich Internet Applications (WAI-ARIA) # switch |
ARIA in HTML # index-aria-switch |