docs.rodeo

MDN Web Docs mirror

ARIA: switch role

{{AccessibilitySidebar}} 

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

Required JavaScript features

Possible effects on user agents and assistive technology

When the switch role is added to an element, the {{Glossary("user agent")}}  handles it like this:

The assistive technology, if it supports the switch role, responds by doing the following:

[!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 {{HTMLElement("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 {{HTMLElement("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 {{cssxref(":first-child")}}  and {{cssxref(":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:

{{EmbedLiveSample("Adding_the_switch_role_in_ARIA", 600, 40)}} 

Specifications

{{Specifications}} 

See also

In this article

View on MDN