Names, roles & states
An ARIA Attribute Is Used Where It Isn't Allowed
Each role allows only certain ARIA attributes, and screen readers ignore any other — so people miss what it was meant to say.
aria-allowed-attrWCAG 2.0Introduced in WCAG 2.0.Level AA — the minimum. Missing it blocks people outright.
- Status
- SeriousSerious — Significant friction, or information that is lost.CurrentScanners run this rule today.
- Owner
- DesignDevTest
- Audit
- Automated+ManualA scanner finds it; a person confirms the fix.
Why it matters
ARIA tells screen readers what a control is and what state it's in — selected, on, or the current page.
If an attribute isn't allowed on that element, the screen reader ignores it. People who can't see the screen miss something everyone else can see.
Who it affects
| Who | What they experience | Impact |
|---|---|---|
| Screen reader users | They don't hear the state — "on", "selected", "current page" — that everyone else can see. | 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 | They can still say the control's name, but they get no state back. | Partial impact |
Business & product impact
| Area | Why | Impact |
|---|---|---|
| Legal | It fails WCAG 4.1.2 at Level A, the minimum. Complaints under Australia's Disability Discrimination Act point to WCAG. | High impact |
| Conversion | A missing state on a filter, size picker or toggle leads to wrong choices and lost sales. | Moderate impact |
| SEO | No real search benefit — don't sell it as one. | Low impact |
| Brand trust | Screen reader users notice quickly, and tell others. | Moderate impact |
| Cost to fix | Usually a one-line fix. Fix it once in the shared component. | High impact |
Fixing it in code
The current page in a menu
Don't
<a href="/" aria-selected="true">Home</a>A screen reader says: “Home, link”
Do
<a href="/" aria-current="page">Home</a>A screen reader says: “Home, current page, link”
Links can't use aria-selected. Use aria-current for the current page.
An on/off toggle
Don't
<button aria-checked="true">Dark mode</button>A screen reader says: “Dark mode, button”
Do
<button role="switch" aria-checked="true">Dark mode</button>A screen reader says: “Dark mode, switch, on”
Buttons can't use aria-checked. Make it a switch, or use aria-pressed.
Designer's handoff note
For each control with a state, write down what the screen reader should say — for example, "Dark mode, switch, on".
Quick test
Tool
VoiceOver (opens in a new tab) (on every Mac)
Checklist
- Pass
- You hear the state, like "current page" or "on".
- Fail
- You hear only the name and role, like "Home, link".
What a green scan still misses
A scanner spots an attribute that isn't allowed. It can't tell whether you picked the right replacement — for that, listen.
Reference
- Rule ID
aria-allowed-attr- Raised by
- axe-core: “Elements must only use supported ARIA attributes”
- Lighthouse: “[aria-*] attributes match their roles”
- 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