Switch

Reported as: Element has incorrect role

A switch must expose the switch role so assistive technology can convey that it turns a setting on or off.

When a control that works as a switch has no role, or a native checkbox or button keeps its own role, assistive technology exposes it as plain content, a checkbox, or a button. Screen reader users hear the wrong kind of control, or no state, and can't tell that it turns a setting on or off.

Add role="switch" to the native checkbox, button, or other element that users operate.

Severity: Critical

Reported as: Incorrect root element

A switch should keep its role, accessible name, state, and tab stop on one element.

When role="switch" sits on a wrapper while the native checkbox or button inside it takes focus, assistive technology describes the focused element, which isn't a switch. Screen reader users land on the control and hear "checkbox" or "button", even though role="switch" is in the markup.

Put role="switch" on the checkbox, button, or element that receives focus, and keep any layout wrapper free of roles and handlers.

Reported as: Accessible name

A switch must have an accessible name that says which setting it turns on or off.

When a switch has no accessible name, assistive technology can report only its role and state, so screen reader users hear "switch, off" with no way to know what it controls. Voice control users have no name to speak to operate it.

Associate a visible <label> with a native checkbox switch. For a button or another element, give it text content or point aria-labelledby to visible text, and use aria-label only when there's no visible text to reference.

Severity: Critical

Reported as: No toggle indicator

A switch built from a button or a non-semantic element must declare its current state with aria-checked.

When the thumb's position is drawn from a CSS class and aria-checked is missing, the switch looks complete but declares no state, so it can be reported as off whatever it shows. Screen reader users can't tell the current setting before they act, or whether their action took effect.

Set aria-checked to true or false when the switch first renders, not on the first interaction, and keep it in step with what's on screen. A native checkbox switch reports its state through checked without any attribute of yours.

Severity: Critical

Reported as: Invalid toggle attribute value

A switch's aria-checked attribute must be set to the string true or false.

When aria-checked carries any other value, such as on, 1, or an empty string, browsers and assistive technology ignore it or assume a default of their own, and screen reader users can hear a state that doesn't match what the switch shows. The value mixed is equivalent to false on a switch, so a switch set to mixed is reported as off whatever it shows.

Convert the application's internal state to true or false in one place, where the attribute is written.

Severity: Moderate

Reported as: State indicated by color alone

A switch must show whether it's on or off with a visual change other than color.

When the only difference between states is the track color, such as gray for off and green for on, people with color vision deficiency or low vision, or using a high-contrast display, can't tell whether the setting is on. Exposing the state to assistive technology doesn't help, because most of these users don't use any.

Move the thumb to the other end of the track or show On and Off text, and keep any color change alongside it. Whatever tells the states apart needs a contrast of at least 3:1 with the colors around it. Draw the thumb and track with an SVG or borders rather than CSS background colors, which high-contrast modes can remove.

Severity: Serious

Reported as: Conflicting disabled values

A switch must have a single, consistent disabled state.

When a switch sets its disabled state two ways and the values disagree, such as the disabled attribute alongside aria-disabled="false", assistive technology may report a state the browser doesn't enforce. Users can't tell whether they're able to change the setting.

Set the disabled state once: the disabled attribute on a native checkbox or button switch, or aria-disabled on a switch built from a non-semantic element, never both.

Severity: Serious

Reported as: Element does not support the disabled attribute

A switch built from a non-semantic element must convey its disabled state with aria-disabled, not the disabled attribute.

When disabled is set on the <div> or <span> behind a switch, the browser ignores it. The switch stays in the accessibility tree as an ordinary, available switch, so users are told they can change a setting the design means to be unavailable, even when styling grays it out.

Set aria-disabled="true" instead, and block activation in code while it's set. When a native checkbox or a button would do the job, use it, and its disabled attribute handles the state, the tab order, and activation.

Severity: Serious

Reported as: Element type does not support disabled state

An element in a switch must carry disabled or aria-disabled only when its role supports a disabled state.

When the state sits on an element whose role has none, such as a wrapper, a list item or a heading, assistive technology may drop it or report it on something users can't operate, while the control that really is unavailable is still reported as available.

Remove the attribute from that element, and set the disabled state on the control itself, using an element or role that supports it, such as a native <button>.

Severity: Serious

Reported as: Forbidden interactive children; Nested interactive elements

A switch must not contain another interactive element, such as a link or a button.

When a control is nested inside a switch, assistive technology users get one control where sighted users see two, and the inner one can't be reached or operated. A click or a key press also has two plausible targets, so it's unclear whether it toggles the switch or activates the inner control.

Move the inner control out of the switch and make the two siblings, each with its own role, accessible name, and activation behavior.

Severity: Serious

Reported as: Avoid aria-owns

A switch should not own other elements with aria-owns.

The switch role allows only presentational children, and browsers and assistive technology handle aria-owns on a switch inconsistently. When a switch owns another element, that element can lose any role it carries, so screen reader users may not be told what it is or that it's there.

Remove aria-owns from the switch, and put only presentational content inside a custom switch. That content can supply the accessible name, or aria-labelledby can reference visible text.

Reported as: Keyboard accessible

A switch must be reachable with the Tab key.

When a switch is built from a <div> or <span> with a role and click handling but no tabindex, keyboard users can't reach it, so they can't turn the setting on or off.

Use a native checkbox or a button, which is focusable on its own, or add tabindex="0" to a switch built from another element so it joins the tab order in document order.

Severity: Critical

Reported as: Disabled element focusable

A switch that presents as disabled shouldn't be in the tab order.

When a disabled switch keeps its tab stop, keyboard users land on a setting they can't change. In a settings panel with several disabled switches, they pass through a stop for each one.

Use the disabled attribute on a native checkbox or button switch, which removes it from the tab order. On a switch built from another element, set tabindex="-1" while aria-disabled="true" is set, and restore tabindex="0" when it becomes available.

Severity: Minor

Reported as: Focusable offset

A switch must receive focus on the element that carries the switch role, not on one of its descendants.

When focus lands on a child of the element with role="switch", such as its thumb or its On and Off text, assistive technology describes that child, which has no role or state. Users tabbing through the page aren't told they've reached a switch or whether it's on.

Build the switch on a native checkbox or button, or add tabindex="0" to the element with the role, and remove focusability from the descendant that was taking focus instead.

Severity: Minor

Reported as: Unexpected context change on input

Changing a switch's state must not change the context unless users are told beforehand that it will.

When toggling a switch reloads the page, submits a form, opens a dialog, or moves focus, screen reader and screen magnifier users may not notice that the page changed. Keyboard users lose their place, and a form that submits partway through can discard what the user hadn't finished entering.

Apply the setting in place and leave focus on the switch. When the change of context is intended, say so in text that comes before the switch.

Severity: Serious

Reported as: Element's state did not change

Activating a switch built from a button or a non-semantic element, with a pointer or the keyboard, must update aria-checked to its new state.

When the thumb moves but aria-checked keeps its starting value, sighted users see the switch toggle while assistive technology reports the old state. A screen reader user who turns the setting on hears no change and, returning to it later, is told it's still off.

Derive aria-checked and the switch's appearance from the same state, and write both in one place. Handle every activation through that one code path.

Evinced reports this issue as Critical or as Serious, depending on the context where it shows up.

Severity: Critical

Reported as: Toggle state not resetting

Activating a switch twice must return its reported state to where it started.

When a handler sets aria-checked to a fixed value instead of inverting it, the switch reports the right state once and then stays there. A user who turns the setting off is told it's still on, and their attempt to correct it appears to change nothing.

Invert the current state on each activation, reading it from the same place that renders it, rather than assigning a fixed value.

Evinced reports this issue as Critical or as Serious, depending on the context where it shows up.

Severity: Critical

Reported as: Invalid toggle attribute

A native checkbox switch must not also carry aria-checked.

When an <input type="checkbox"> with role="switch" has aria-checked alongside its own checked property, the two can disagree. The browser updates checked on every activation, while aria-checked holds whatever value the code last wrote, so a switch the user has just turned on can be reported as off.

Remove aria-checked from the native checkbox and let checked report the state. Keep aria-checked for a switch built from a button or another element, which has no native state to report.

Severity: Serious

Reported as: Toggle name not resetting

A switch's accessible name must never report a state the switch isn't in.

When the visible On or Off text inside a switch is part of its accessible name and updates only on the first toggle, the name then contradicts the state. Screen reader users hear "Dark mode on, switch, off" and can't tell which to believe. Voice control users who say what they hear may not reach the switch.

Hide the On and Off text with aria-hidden="true", so the name stays fixed and aria-checked or checked reports the state.

Severity: Serious

Reported as: Disabled element active

A switch that presents as disabled must not change state when it's activated.

When a switch built from a non-semantic element carries aria-disabled="true" but keeps its click and key handlers, activating it still toggles aria-checked. Screen reader users hear the switch announced as unavailable and then hear its state change, so they can't trust either signal or tell whether the setting changed.

Check the disabled state at the start of the toggle handler and return before changing anything, covering the pointer and keyboard paths. For a native checkbox or button, the disabled attribute blocks activation with no code.

Severity: Moderate

Reported as: Deprecated keypress listener

A switch's key handling should use keydown or keyup, not keypress.

When a handler listens for keypress, keys the browser doesn't send through that event go unanswered, and keyboard users find the switch ignoring keys it's meant to respond to.

Replace each keypress listener with a keydown listener, and read the key from event.key.

Severity: Minor

Most relate to 4.1.2 Name, Role, Value: the switch's role, its accessible name, its on or off state and the values it takes, how it conveys a disabled state, updating and reversing that state on activation, keeping its name in step with its state, and keeping other interactive elements out of it.

Reaching the switch with the Tab key and putting focus on the element with the role relate to 2.1.1 Keyboard. Showing the state by more than color relates to 1.4.1 Use of Color, keeping the context when the state changes to 3.2.2 On Input, and a disabled switch that still changes state to 1.3.1 Info and Relationships.

Taking a disabled switch out of the tab order maps to no WCAG success criterion and is a best practice.

Severity reflects how much an issue gets in users' way. Critical issues stop users outright: a switch with no role, name, or reported state, one keyboard users can't reach, or one whose reported state doesn't follow activation. Serious issues confuse users though tasks are still possible, such as showing the state by color alone, reporting a disabled or on state the switch doesn't have, letting its name contradict the state, nesting controls, or changing the context without warning.

An invalid aria-checked value, or a disabled switch that still toggles, is Moderate. A disabled switch left in the tab order, or focus that lands inside the switch rather than on it, is Minor.

The aria-owns check and the check on where the role sits carry no severity: Evinced reports them as a general check and a sanity check.