mixed-aria-state-attributes

Some ARIA attributes describe what kind of control a button is, and how it behaves. Two of them are easy to mix up:

• aria-pressed makes a button a toggle button. It reports an on or off state of the button itself, like a Mute or Bold button.
• aria-expanded, often together with aria-controls, makes a button a disclosure button. It reports whether another part of the page, like a menu or a panel of filters, is shown or hidden.

A button can be one or the other, but not both. When a button has aria-pressed and also aria-expanded or aria-controls, assistive technology receives two state models for the same control. Screen readers may announce both states, or only one of them, depending on the screen reader and browser. Either way, users can't tell what the button does or what state it's in, which makes the interface hard to understand and operate.

To fix the issue, decide what the button does, and keep only the attributes for that purpose:

• If activating the button shows or hides another part of the page that users are meant to reach, it's a disclosure button. Remove aria-pressed.
• If activating the button changes a state without showing additional content, it's a toggle button. Remove aria-expanded and aria-controls.

Pass Patterns

Disclosure button

The button shows and hides a panel, so it uses aria-expanded and aria-controls only.

<button aria-expanded="false" aria-controls="filters">Filters</button>
<div id="filters" hidden>
    <!-- Filter options -->
</div>

Toggle button

The button turns a setting on and off, so it uses aria-pressed only.

<button aria-pressed="false">Mute</button>

Fail Patterns

Button with both aria-pressed and aria-expanded

The button shows and hides a panel, but it also reports a pressed state, so assistive technology gets two conflicting states.

<button aria-pressed="true" aria-expanded="true" aria-controls="filters">Filters</button>
<div id="filters">
    <!-- Filter options -->
</div>

Toggle button with aria-controls

The button only turns a setting on and off, but aria-controls gives it a disclosure relationship it doesn't have.

<button aria-pressed="false" aria-controls="player">Mute</button>

WCAG techniques

Sufficient techniques

• ARIA5: Using WAI-ARIA state and property attributes to expose the state of a user interface component
• G108: Using markup features to expose the name and role, allow user-settable properties to be directly set, and provide notification of changes

Try It Yourself

Using a screen reader

1. Load the page and open a screen reader.
2. Move to the button and listen to what the screen reader announces.
3. Activate the button, and listen again.

Expected results: The screen reader announces one kind of state: either pressed or not pressed for a toggle button, or expanded or collapsed for a disclosure button.

Actual results: The screen reader announces both a pressed state and an expanded state, or the announced state doesn't match what the button does.

Inspecting the browser dev-tools

1. In your browser's dev tools, select the button and open the Accessibility panel.
2. Check the button's states and properties.

Expected results: The button has either a pressed state, or an expanded state with an optional aria-controls reference, but not both.

Actual results: The button has a pressed state together with an expanded state or an aria-controls reference.

FAQ

Standards and Regulations

Personas impacted by this issue

• Screen Reader
• Braille

Learn More

• WAI-ARIA Authoring Practices: Disclosure (Show/Hide) Pattern
• WAI-ARIA Authoring Practices: Button Pattern (including toggle buttons)
• WAI-ARIA 1.3: aria-pressed
• WAI-ARIA 1.3: aria-expanded
• Disclosure and Toggle Button UI patterns
• Relationships Between ARIA Roles and Attributes

Related Issues

• aria-allowed-attr
• aria-valid-attr-value
• interactable-role