Names, roles & states
A Custom Button, Link or Menu Item Has No Name
A control built with role="button", "link" or "menuitem" has no name, so screen reader users hear only "button" and can't tell what it does.
aria-command-nameWCAG 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
- DesignDevContentTest
- Audit
- Automated+ManualA scanner finds it; a person confirms the fix.
Why it matters
Some teams turn a div or span into a control by giving it role="button", role="link" or role="menuitem". Screen readers then announce it as a control. But they also need a name — words that say what it does.
If the control shows only an icon, or the name is missing, people hear "button" and nothing else. They must guess, or press it and hope.
Who it affects
| Who | What they experience | Impact |
|---|---|---|
| Screen reader users | They hear "button" or "link" with no name, so they don't know what it does. | High impact |
| Voice control users | They can't say a name to press it, so they fall back on slow grid or number commands. | High impact |
| Low-vision users (magnification) | Affected if they use a screen reader or magnifier with speech, as many do. | Partial impact |
| Cognitive and neurodivergent users | An icon with no words can be hard to understand. A visible label helps everyone. | Partial impact |
Business & product impact
| Area | Why | Impact |
|---|---|---|
| Legal | It fails WCAG 4.1.2 at Level A, the minimum, and EN 301 549. Complaints under Australia's Disability Discrimination Act point to WCAG 2.2 AA. | High impact |
| Conversion | Unnamed "Add to cart", "Next" or menu controls stop people finishing tasks. | High impact |
| SEO | Little or no search benefit. Don't sell it as one. | Low impact |
| Brand trust | A page full of "button, button, button" feels broken. Users notice and tell others. | Moderate impact |
| Cost to fix | Usually a small fix. Fix the shared icon-button component once and it's fixed everywhere. | High impact |
Fixing it in code
An icon-only close control
Don't
<div role="button" tabindex="0"><svg aria-hidden="true">…</svg></div>A screen reader says: “button”
Do
<div role="button" tabindex="0" aria-label="Close"><svg aria-hidden="true">…</svg></div>A screen reader says: “Close, button”
aria-label gives the control a name screen readers can read.
A menu item with an empty span
Don't
<li role="menuitem"><span class="icon-print"></span></li>A screen reader says: “menu item”
Do
<li role="menuitem"><span class="icon-print" aria-hidden="true"></span> Print</li>A screen reader says: “Print, menu item”
Visible text inside the control becomes its name.
Better still: use a real button
Don't
<span role="button" tabindex="0" class="icon-search"></span>A screen reader says: “button”
Do
<button type="button"><span class="icon-search" aria-hidden="true"></span> Search</button>A screen reader says: “Search, button”
A native button handles keys and focus for you, and takes its text as the name.
Designer's handoff note
Give every icon-only control a written name in your design file, such as "Close" or "Next slide".
Where you can, show a visible text label. It helps voice control and cognitive users too.
Quick test
Tool
NVDA (opens in a new tab) (free on Windows) or VoiceOver (opens in a new tab) (on every Mac)
Checklist
- Pass
- Every control says what it does, like "Close, button".
- Fail
- You hear only a role, like "button" or "menu item", with no name.
What a green scan still misses
A scanner finds controls with no name at all. It can't tell if a name like "icon" or "click here" actually makes sense — for that, listen.
Reference
- Rule ID
aria-command-name- Raised by
- axe-core: “ARIA commands must have an accessible name”
- 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 11.9.1
- Last reviewed
- 14 October 2026