Using the 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."

Assistive technologies may choose to represent switch widgets with a specialized presentation to reflect the notion of an on/off switch. Unlike the checked role, switch does not support the value mixed; assigning a value of mixed to a switch instead sets the value to false.

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 the switch role.
  • All elements that are descendants of an element with the switch role applied to it are automatically assigned role presentation. 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 using display: none or aria-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.

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" tabindex="0"
      id="speakerPower" class="switch">
  <span>off</span>
  <span>on</span>
</button>
<label for="speakerPower" class="switch">Speaker power</label>

JavaScript

document.querySelectorAll(".switch").forEach(function(theSwitch) {
  theSwitch.addEventListener("click", handleClickEvent, false);
});

function handleClickEvent(evt) {
  let el = evt.target;
 
  if (el.getAttribute("aria-checked") == "true") {
      el.setAttribute("aria-checked", "false");
  } else {
      el.setAttribute("aria-checked", "true");
  }
}

CSS

The role of the CSS is to establish a look and feel for the switch that's reminiscient of the power switch paradigm we're trying to follow.

button.switch {
  margin: 0;
  padding: 0;
  width: 60px;
  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;}

[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;
  user-select: none;
  vertical-align: middle;
  -moz-user-select: none;
  -ms-user-select: none;
  -webkit-user-select: none;
  -o-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:

ARIA attributes used

  • aria-checked

Specifications

Specification Status Comment
Accessible Rich Internet Applications (WAI-ARIA) Recommendation Defines ARIA in general along with all roles, properties, and so forth.
ARIA in HTML Working Draft Describes how ARIA's features integrate into HTML.

See also

Document Tags and Contributors

 Contributors to this page: fscholz, scottaohara, access-sandeep, Sheppy, teoli, chrisdavidmills
 Last updated by: fscholz,