Names, roles & states
An ARIA Attribute Has a Value That Isn't Allowed
When an ARIA attribute holds a wrong or misspelled value, screen readers ignore it or guess — so people miss whether something is open, checked or current.
aria-valid-attr-valueWCAG 2.0Introduced in WCAG 2.0.Level AA — the minimum. Missing it blocks people outright.
- Status
- CriticalCritical — Someone can complete the task only with great difficulty or outside help.CurrentScanners run this rule today.
- Owner
- DesignDevTest
- Audit
- Automated+ManualA scanner finds it; a person confirms the fix.
Why it matters
ARIA attributes tell screen readers about a control. Is it open? Is it checked? Which label belongs to it? Each attribute only accepts certain values, like true or false, or the ID of a real element.
A typo, a wrong word or an ID that doesn't exist breaks this. The screen reader skips the information or reports the wrong state. People who can't see the screen are left guessing.
Who it affects
| Who | What they experience | Impact |
|---|---|---|
| Screen reader users | They hear no state, or the wrong one — a menu that sounds closed when it's open, or a field with no label. | High impact |
| Low-vision users (magnification) | Affected only if they also use a screen reader, as many do. | Partial impact |
| Cognitive and neurodivergent users | When the voice says one thing and the screen shows another, it's confusing. | Partial impact |
| Voice control users | If the broken value was meant to name a control, they may not know what to say to click it. | Partial impact |
Business & product impact
| Area | Why | Impact |
|---|---|---|
| Legal | Broken names and states fall under WCAG 4.1.2 at Level A, the minimum. Complaints under Australia's Disability Discrimination Act point to WCAG 2.2 Level AA, and EN 301 549 applies in Europe. | High impact |
| Conversion | A menu, accordion or checkbox that reports the wrong state can stop people finishing a task or a purchase. | Moderate impact |
| SEO | No real search benefit — don't sell it as one. | Low impact |
| Brand trust | Controls that seem broken to screen reader users erode trust fast. | Moderate impact |
| Cost to fix | Usually a small fix. Fix it once in the shared component and it's fixed everywhere. | High impact |
Fixing it in code
A menu button that opens and closes
Don't
<button aria-expanded="yes">Menu</button>A screen reader says: “Menu, button”
Do
<button aria-expanded="false">Menu</button>A screen reader says: “Menu, collapsed, button”
aria-expanded only accepts true or false, not "yes".
A field linked to its hint
Don't
<input id="email" aria-describedby="email-hnt">
<p id="email-hint">We never share your email.</p>A screen reader says: “Edit text”
Do
<input id="email" aria-describedby="email-hint">
<p id="email-hint">We never share your email.</p>A screen reader says: “Edit text, We never share your email.”
The value must match the id of an element that exists on the page.
Designer's handoff note
For each control that changes state, note every state it can be in — for example, "collapsed" and "expanded". Developers then know which values to set.
Quick test
Tool
NVDA (opens in a new tab) (free on Windows) or VoiceOver (opens in a new tab) (on every Mac)
Checklist
- Pass
- You hear the right state, like "expanded", or the hint text read out.
- Fail
- You hear no state, the wrong state, or no hint.
Check these at the same time
- An ARIA attribute is used where it isn't allowed
aria-allowed-attr - A role is missing an ARIA attribute it needs
aria-required-attr
What a green scan still misses
A scanner can tell a value is invalid. It can't tell whether a valid value matches what's on screen, like aria-expanded="false" on an open menu — for that, listen.
Reference
- Rule ID
aria-valid-attr-value- Raised by
- axe-core: “ARIA attributes must conform to valid values”
- WCAG
- 4.1.2 Name, Role, Value (opens in a new tab) · Level A · since WCAG 2.0
- Other standards
- EN 301 549 9.4.1.2 · RGAA 7.1.1
- Last reviewed
- 14 October 2026