Expose widget state with ARIA attributes
ARIA state and property attributes carry what a component is doing right now. aria-expanded for a disclosure, aria-checked for a custom checkbox, aria-selected for a tab, aria-valuenow with its minimum and maximum for a slider. W3C lists ARIA5 as sufficient for 4.1.2 Name, Role, Value in combination with the general technique for exposing name and role, and that technique's own title ends with the words that matter here, notification of changes. Setting the attribute once at render is not the technique. Keeping it in step every time your script changes the widget is. A slider is the case that catches teams out, because aria-valuenow, aria-valuemin and aria-valuemax all have to move together and stay consistent with what the thumb is showing.
How we find it in an audit
Missing state attributes on elements that clearly have state are an automated find. Stale ones are not. So we operate each widget and watch the attribute in the inspector while we do it. Open the accordion and check aria-expanded flipped. Drag the slider and check the value followed. A widget that reports its opening state forever is the common defect and no scanner will ever see it.
How affected users experience it
A screen-reader user presses a Filters button and hears collapsed, because the attribute never changed. The panel is open on screen. Now they have a menu they believe is shut, sitting over content they cannot find, and nothing in what they heard will correct them. Wrong state is more expensive than missing state, because a person acts on it.
Passes vs. fails
Passes
<button aria-expanded="true" aria-controls="filter-panel" onclick="toggle()">Filters</button>Fails
<button class="open" onclick="toggle()">Filters</button>How this gets tested
The W3C publishes test rules that define what a checker looks for here.
- Image button has non-empty accessible nameA tool can check this
- Link has non-empty accessible nameA tool can check this
- ARIA attribute is defined in WAI-ARIAA tool can check this
- ARIA state or property has valid valueA tool can check this
- Element with role attribute has required states and propertiesA tool can check this
- Form field has non-empty accessible nameA tool can check this
- Role attribute has valid valueA tool can check this
- ARIA state or property is permittedA tool can check this
- Button has non-empty accessible nameA tool can check this
- Element with aria-hidden has no content in sequential focus navigationA tool can check this
- Element with presentational children has no focusable contentA tool can check this
- Menuitem has non-empty accessible nameA tool can check this
- Summary element has non-empty accessible nameA tool can check this
- Iframe element has non-empty accessible nameA tool can check this
- Iframe elements with identical accessible names have equivalent purposeA tool finds candidates, you decide
Other ways to satisfy this rule
23 guides on this site are filed under 4.1.2 Name, Role, Value. W3C lists this one as sufficient for that rule only alongside G10, so the pair is what passes and neither half does on its own.
- ARIA4sufficientGive custom widgets a real ARIA role
- ARIA14sufficientLabel icon-only controls with aria-label
- ARIA16sufficientName controls from visible text with aria-labelledby
- G10sufficientBuild custom components on accessibility-supported tech
- G108sufficientExpose name, role, and changes through markup
- G135sufficientExpose controls through the platform accessibility API
This guide is our interpretation of W3C technique ARIA5: Using WAI-ARIA state and property attributes to expose the state of a user interface component. W3C publishes its techniques as guidance rather than as the standard, and says so on every one of them. The success criterion is what conformance is measured against, and a technique is one documented way to meet it.