The ARIAswitch role is functionally identical to thecheckbox role, except that instead of representing "checked" and "unchecked" states, which are fairly generic in meaning, theswitch role represents the states "on" and "off."

This example creates a widget and assigns the ARIAswitch role to it.

<button  type="button"  role="switch"  aria-checked="true"  >  <span aria-hidden="true">off</span>  <span aria-hidden="false">on</span></button><label for="speakerPower">Speaker power</label>

Description

The ARIAswitch role is identical to thecheckbox role, except instead of being "checked" or "unchecked", it is either "on" or "off". Like thecheckbox role, thearia-checked attribute is required. The two possible values aretrue andfalse. Unlike an<input type="checkbox"> orrole="checkbox", there is noindeterminate ormixed state. Theswitch role does not support the valuemixed for thearia-checked attribute; assigning a value ofmixed to aswitch instead sets the value tofalse.

Assistive technologies may choose to representswitch 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 thetabindex attribute to change this. The expected keyboard shortcut for toggling the value of a switch is theSpace key. The developer is required to change the value of thearia-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 aswitch. To deal with this limitation, browsers, automatically apply rolepresentation to all descendant elements of anyswitch element as it is a role that does not support semantic children.

For example, consider the followingswitch element, which contains a heading.

<div role="switch"><h3>Title of my switch</h3></div>

Because descendants ofswitch 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 theaccessibility tree:

<div role="switch">Title of my switch</div>

Associated ARIA roles, states, and properties

aria-checked attribute

Thearia-checked attribute isrequired 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

Thearia-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 usercan change the widget's state; a value oftrue means that the usercannot change the widget's state. The default value isfalse.

Required JavaScript features

Handler for click events

When the user clicks on the switch widget, aclick event is fired, which must be handled in order to change the state of the widget.

Changing thearia-checked attribute

When a click event is fired on the switch widget, the handler must change the value of thearia-checked attribute fromtrue tofalse, or vice versa.

Possible effects on user agents and assistive technology

When theswitch role is added to an element, theuser agent handles it like this:

• The element is exposed to the system's accessibility infrastructure as having theswitch role.
• When thearia-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 theswitch 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 theswitch 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 theswitch role.

Adding the switch role in ARIA

This example creates a widget and assigns the ARIAswitch 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 itsaria-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">  <span>off</span>  <span>on</span></button><label for="speakerPower">Speaker power</label>

JavaScript

This JavaScript code defines and applies a function to handle click events on switch widgets. The function changes thearia-checked attribute fromtrue tofalse, 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