Names, roles & states
An ARIA Attribute Name Is Misspelled or Made Up
Screen readers ignore any ARIA attribute with a wrong name, so a label, hint or hidden setting silently never reaches the person.
aria-valid-attrWCAG 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
- DevTest
- Audit
- AutomatedA scanner finds it, and a clean scan means it's fixed.
Why it matters
ARIA attributes are extra code that tell screen readers what something is called, or what to skip. Each has an exact name, like aria-labelledby or aria-hidden.
One wrong letter and the browser treats it as noise. A button can lose its name, or decorative clutter gets read aloud. Nothing looks broken on screen, so teams rarely notice.
Who it affects
| Who | What they experience | Impact |
|---|---|---|
| Screen reader users | They may hear just "button" with no name, or hear icons and clutter that should have been hidden. | High impact |
| Low-vision users (magnification) | Affected only if they also use a screen reader, as many do. | Partial impact |
| Voice control users | If the misspelt attribute was meant to name a control, they have no name to say to click it. | Partial impact |
Business & product impact
| Area | Why | Impact |
|---|---|---|
| Legal | It relates to WCAG 4.1.2 Name, Role, Value at Level A, part of WCAG 2.2 AA and EN 301 549. Complaints under Australia's Disability Discrimination Act point to WCAG. | High impact |
| Conversion | An unnamed cart, search or checkout button can stop a screen reader user from buying. | Moderate impact |
| SEO | No real search benefit — don't sell it as one. | Low impact |
| Brand trust | It signals nobody tested with a screen reader. Users notice. | Low impact |
| Cost to fix | A spelling fix, often in one shared component. Linting can stop it coming back. | High impact |
Fixing it in code
A misspelt label link on an icon button
Don't
<h2 id="cart-title">Shopping cart</h2>
<button aria-labeledby="cart-title"><svg>…</svg></button>A screen reader says: “button”
Do
<h2 id="cart-title">Shopping cart</h2>
<button aria-labelledby="cart-title"><svg>…</svg></button>A screen reader says: “Shopping cart, button”
The correct spelling has two Ls: aria-labelledby.
A decorative arrow meant to be hidden
Don't
<a href="/offers">See offers <span aria-hiden="true">→</span></a>A screen reader says: “See offers right arrow, link”
Do
<a href="/offers">See offers <span aria-hidden="true">→</span></a>A screen reader says: “See offers, link”
With the right name, aria-hidden actually hides the arrow.
An invented attribute
Don't
<div aria-role="alert">Payment failed</div>A screen reader says: “(nothing — the message is not announced when it appears)”
Do
<div role="alert">Payment failed</div>A screen reader says: “Payment failed”
There is no aria-role. Use the plain role attribute.
Designer's handoff note
In handoff notes, write what each icon button should be called and which parts are decorative. Developers can then check the code says the same.
Quick test
Tool
VoiceOver (opens in a new tab) (on every Mac)
Checklist
- Pass
- Every button has a clear name, like "Shopping cart, button".
- Fail
- You hear just "button", or decorative symbols read aloud.
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 - A button has no name a screen reader can say
button-name
What a green scan still misses
A scanner catches names that don't exist. It can't catch a real attribute used for the wrong job, or a label that's spelt right but says the wrong thing.
Reference
- Rule ID
aria-valid-attr- Raised by
- axe-core: “ARIA attributes must conform to valid names”
- 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