ARIA: switch role

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 the switch role, as it represents the current state of the widget that the switch role is applied to. A value of true represents the "on" state; false represents the "off" state; a value of mixed is not supported by the switch role, and is treated as false.

aria-readonly attribute

The aria-readonly attribute is supported by the switch role. It indicates whether the widget's state is editable by the user. A value of false means that the user can change the widget's state; a value of true means that the user cannot change the widget's state. The default value is false.

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 from true to false, 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 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.

Examples

The following examples should help you understand how to apply and use the switch role.

Adding the switch role in ARIA

This example 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

A 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);
});

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;
  vertical-align: middle;
  text-align: center;
  font:
    12px / 20px "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: #226622;
  color: #eeeeff;
}

[role="switch"][aria-checked="false"] :last-child,
[role="switch"][aria-checked="true"] :first-child {
  color: #bbbbdd;
}

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

See also

• ARIA: checkbox role
• <input type="checkbox">
• aria-hidden