Toggle Button

Reported as: Element has incorrect role

A toggle button must carry the button role.

When a toggle button built from a <div> or <span> has no role, or carries another one, screen readers don't announce it as a toggle button even when it sets aria-pressed, and users can't tell they can press it.

Use a <button> element, or set role="button" on a custom toggle button.

Severity: Critical

Reported as: Incorrect root element

The button role should sit on the same element that receives focus, carries aria-pressed, and handles activation.

When the role sits on a descendant while a wrapper takes focus or handles the click, screen readers announce a button that isn't the element users operate, and they may not hear its pressed state.

Put the role, the accessible name, aria-pressed, the ability to focus, and the activation handling on that one element, and keep any wrapper free of roles and handlers.

Reported as: Accessible name

A toggle button must have an accessible name that identifies the mode or condition it controls.

When an icon-only toggle button, such as a toolbar "B" for bold, has no text alternative, screen readers announce only "toggle button, pressed" or "not pressed," and users can't tell what is turned on.

Give the button a name through visible text, an image's alt text, or an aria-label attribute.

Severity: Critical

Reported as: No toggle indicator

A toggle button must declare its current state with aria-pressed.

When the pressed look comes from a CSS class and aria-pressed is missing, assistive technologies report a plain button. Screen reader users can't tell that it toggles, whether the mode is on, or whether their press took effect.

Set aria-pressed to true, false, or mixed when the button first renders. Use mixed only when the button controls several items that don't all share one state.

Severity: Critical

Reported as: Invalid toggle attribute value

The aria-pressed attribute on a toggle button must be set to a recognized value: true, false, or mixed.

When aria-pressed carries a value the spec doesn't define, such as "checked", "on", "yes", or an empty string, browsers and assistive technology ignore it or assume a default of their own, so screen reader users can be told the button isn't pressed, or hear it as a plain button, whatever it shows.

Set it to true when the button is pressed, false when it's not, and mixed only when the button represents a group of two-state items whose individual states don't all match.

Severity: Moderate

Reported as: State indicated by color alone

A toggle button must show whether it's pressed with a visual change other than color.

When the only difference between states is the button's background or text color, such as a "Bold" button that turns blue when pressed, people with color vision deficiency or low vision, or using a high-contrast display, can't tell whether the mode is on. Exposing the state to assistive technology doesn't help, because most of these users don't use any.

Add a cue that changes with aria-pressed, such as a thicker or inset border, a filled icon, or a checkmark, 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 cue with an SVG, a border, or text rather than a CSS background color, which high-contrast modes can remove.

Severity: Serious

Reported as: Conflicting disabled values

A toggle button must declare its disabled state one way only: the disabled attribute on a native <button>, or aria-disabled on a custom toggle button.

When a native button carries aria-disabled instead of disabled, it stays operable and in the tab order while assistive technology reports it as disabled. When both attributes are set and disagree, assistive technology can report a state the browser doesn't enforce. Either way, screen reader users are told the wrong thing about whether the button works.

Use disabled alone on a native <button> and aria-disabled alone on a custom toggle button, removing it or setting it to false when the button is enabled again.

Severity: Serious

Reported as: Element does not support the disabled attribute

A toggle button built from an element that doesn't support the disabled attribute must convey its disabled state with aria-disabled instead.

When disabled is set on a custom toggle button built from a <div> or <span>, browsers ignore it. The button looks unavailable but still toggles, and assistive technology doesn't report it as disabled, so users can change a mode that's meant to be locked.

Set aria-disabled="true", and block activation in the button's event handlers while it's set.

Severity: Serious

Reported as: Element type does not support disabled state

An element in a toggle button 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 toggle button must not contain or be nested inside another interactive element, such as a link or another button.

A toggle button's children are presentational, so a control nested inside it can't be perceived or operated as a control by screen reader users, and pointer users can't tell whether a click toggles the button or operates the nested control.

Place any other control beside the toggle button, not inside it.

Severity: Serious

Reported as: Avoid aria-owns

A toggle button should not use aria-owns.

When a toggle button owns an element, such as the content its state affects, that element becomes a presentational child of the button. Assistive technology users perceive it only as part of the button's name and can't operate anything interactive inside it.

Remove aria-owns and keep the content outside the button. When the button affects that content, reference it with aria-controls instead.

Reported as: Keyboard accessible

A toggle button must be reachable in the keyboard tab order.

When a toggle button is built from markup that isn't focusable, such as a <div> or <span>, pointer users can press it, but keyboard users can't reach it to change the mode it controls.

A native <button> element is focusable by default. Give a custom toggle button tabindex="0".

Severity: Critical

Reported as: Disabled element focusable

A disabled toggle button should not be a stop in the tab order.

When a disabled toggle button stays in the tab order, keyboard users land on a control they can't press. Screen reader users are told it's disabled, but the tab stop gives them nothing to do.

A native <button> with disabled leaves the tab order on its own. For a custom toggle button, set tabindex="-1" while aria-disabled="true" is set, and tabindex="0" when it's enabled.

Severity: Minor

Reported as: Focusable offset

The element that carries the button role and aria-pressed must be the element that receives focus, not one of its descendants.

When a descendant takes focus instead, screen readers announce that element rather than the toggle button and its pressed state, and keyboard users may not be able to toggle it with Enter or Space.

Set tabindex="0" on the element that carries the role, and on no element inside it.

Severity: Minor

Reported as: Button not activated by keyboard

Keyboard users must be able to activate a toggle button.

When a custom toggle button handles only the click event, pointer users can turn its mode on and off, but keyboard users can focus it and still can't change anything.

Use a native <button>, or add key handlers that toggle a custom button through the same code path as a click.

Severity: Critical

Reported as: Disabled button keyboard activation

A toggle button that reports itself as disabled should not respond to Enter or Space.

When a custom toggle button carries aria-disabled="true" but its key handlers still run, screen reader users are told it's unavailable and then hear its state change, so they can't trust either signal.

Use a native <button> with disabled, which blocks activation automatically. For a custom toggle button, return from the key handlers while aria-disabled="true" is set.

Severity: Serious

Reported as: Button requires space key activation

A custom toggle button must activate with both Enter and Space, as a <button> element does.

When a toggle button answers only one of the two keys, users who press the other, as they would on any other button, conclude it's unresponsive.

Activate a custom toggle button on an Enter keydown event and a Space keyup event, or use a native <button>.

Severity: Minor

Reported as: Toggle state not updated

A button that toggles a state must report every press, either through aria-pressed on a toggle button or through the name of a command button.

When a press changes neither, screen reader users aren't told that anything happened and can't tell what state the button is in, so they may press it again and undo what they meant to do.

On a toggle button, toggle aria-pressed between true and false and keep the name fixed. On a command button, change the name to the command it now performs. Handle pointer and keyboard activation through one code path.

Severity: Critical

Reported as: Element's state did not change

Activating a toggle button that carries aria-pressed, with a pointer or the keyboard, must update aria-pressed to its new state.

When aria-pressed keeps its starting value, assistive technology reports the old state after every press. A screen reader user who turns on "Bold" hears no change and, returning to the button later, is told it's still not pressed.

Update aria-pressed in the code that toggles the button's state, and handle pointer and keyboard 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 toggle button twice must return its reported state to where it started. A toggle button toggles both the mode or condition it controls and its reported state.

If the reported state stays the same or changes to yet another value on the next activation, users can't tell what the button does and can't set or reset the condition or mode it controls.

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

Severity: Critical

Reported as: Toggle button overlapping changes

Activating a toggle button must change its aria-pressed value without changing its accessible name.

When the button updates aria-pressed and swaps its name on the same activation, a screen reader announces something inconsistent, such as "Pause, pressed," that can confuse users about the actual state.

Keep the name fixed and let aria-pressed carry the state. If the name has to change, make it a command button by removing aria-pressed.

Severity: Serious

Reported as: Toggle name not resetting

A command button, which has no aria-pressed, must change its accessible name every time it's activated.

When a "Play" button becomes "Pause" on the first press and then keeps that name, the name contradicts the player's state. Screen reader users hear "Pause" while nothing is playing, and voice control users who say the name they see may not reach the button.

Compute the name from the current state every time the state changes, rather than setting it once. Or make it a toggle button: Keep the name fixed and let aria-pressed carry the state.

Severity: Serious

Reported as: Disabled element active

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

When a button is styled as unavailable, or carries aria-disabled="true", but its click and key handlers are enabled, activating it still changes the state. Users are told the button isn't available and then find it responds, leaving them unable to trust either signal.

Check the disabled state at the start of the handler and return without changing anything, covering both the pointer and keyboard paths. For a native button, using the HTML disabled attribute prevents activation in the browser without any additional code.

Severity: Moderate

Reported as: Deprecated keypress listener

A toggle button'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 toggle button 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 toggle button issues relate to 4.1.2 Name, Role, Value: the button role, an accessible name, a valid aria-pressed state that follows each activation, a name that stays fixed while the state changes, a correctly conveyed disabled state, and no nested interactive elements.

Reaching the button by keyboard, focus landing on the element that carries the role, and activating it with Enter and Space relate to 2.1.1 Keyboard. Showing the pressed state by more than color relates to 1.4.1 Use of Color, and a disabled toggle button that still changes state relates to 1.3.1 Info and Relationships.

Two criteria map to no WCAG success criterion and are best practices: removing a disabled toggle button from the tab order, and ignoring the keyboard when it's disabled.

Severity reflects how much an issue gets in users' way. Critical issues stop users outright: a toggle button with no role, name, or declared state, one keyboard users can't reach or activate, 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, a wrong disabled state, nested controls, a name that changes along with the state, a command button's name that stops changing, or a disabled button that still responds to the keyboard.

An invalid aria-pressed value, or a disabled toggle button that still changes state, is Moderate. A custom toggle button that ignores Enter or Space, focus that lands inside the button rather than on it, or a disabled button left in the tab order 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.