Names, roles & states
A Control's Hidden Name Doesn't Include Its Visible Words
The button says one thing on screen but has a different hidden name, so people who speak commands or use screen readers can't match them up.
label-content-name-mismatchWCAG 2.1Introduced in WCAG 2.1.Level AA — the minimum. Missing it blocks people outright.
- Status
- SeriousSerious — Significant friction, or information that is lost.Experimentalaxe-core has this rule, but runs it only when a team turns experimental rules on.
- Owner
- DesignDevContentTest
- Audit
- Automated+ManualA scanner finds it; a person confirms the fix.
Experimental rule. Experimental in axe-core: it runs only when a team turns experimental rules on, so a clean default scan says nothing about it. WCAG 2.5.3 Label in Name still applies.
Why it matters
Every button and link has a hidden name that software reads out. This is called the accessible name. Often it's set with aria-label, which replaces the visible text.
Voice control users say what they see, like "click Search". If the hidden name doesn't contain "Search", nothing happens. Screen reader users who can see the screen also hear words that don't match it.
Who it affects
| Who | What they experience | Impact |
|---|---|---|
| Voice control users | They say "click Search" and nothing happens, because the hidden name is "Find products". | High impact |
| Screen reader users | They hear a name that differs from the screen, which confuses anyone who can partly see it. | Partial impact |
| Low-vision users (magnification) | Those who use a screen reader with magnification hear words that don't match what they see. | Partial impact |
| Cognitive and neurodivergent users | When the spoken words don't match the visible words, it's hard to know which control is which. | Partial impact |
Business & product impact
| Area | Why | Impact |
|---|---|---|
| Legal | It fails WCAG 2.5.3 Label in Name 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 | If voice users can't press "Add to cart" or "Pay now", they can't buy. | Moderate impact |
| SEO | No real search benefit — don't sell it as one. | Low impact |
| Brand trust | People who rely on voice control give up and tell others the site doesn't work. | Moderate impact |
| Cost to fix | Usually a quick fix: remove the `aria-label` or start it with the visible words. | High impact |
Fixing it in code
A search button with a different label
Don't
<button aria-label="Find products">Search</button>A screen reader says: “Find products, button”
Do
<button>Search</button>A screen reader says: “Search, button”
With no aria-label, the visible text becomes the name.
Adding extra detail to a link
Don't
<a href="/report" aria-label="Download the 2024 annual report">Read more</a>A screen reader says: “Download the 2024 annual report, link”
Do
<a href="/report">Read more<span class="visually-hidden"> about the 2024 annual report</span></a>A screen reader says: “Read more about the 2024 annual report, link”
The name starts with the visible words, so "click Read more" works.
Designer's handoff note
Write button and link text that makes sense on its own, so no hidden label is needed.
If extra context is needed for screen readers, put it after the visible words, never instead of them.
Quick test
Tool
VoiceOver (opens in a new tab) (on every Mac)
Duration
2 minChecklist
- Pass
- Every name you hear contains the visible words, ideally at the start.
- Fail
- You hear different words, like "Find products" for a button that says "Search".
Check these at the same time
- An ARIA attribute is used where it isn't allowed
aria-allowed-attr - A button has no name a screen reader can say
button-name - A form field has no label
label - A link has no text a screen reader can read
link-name
What a green scan still misses
This rule is experimental and only checks text it can read. It misses text inside images and icons, and can't judge whether added words still make sense.
Reference
- Status
- ExperimentalExperimental in axe-core: it runs only when a team turns experimental rules on, so a clean default scan says nothing about it. WCAG 2.5.3 Label in Name still applies.
- Rule ID
label-content-name-mismatch- Raised by
- axe-core: “Elements must have their visible text as part of their accessible name”
- WCAG
- 2.5.3 Label in Name (opens in a new tab) · Level A · since WCAG 2.1
- Other standards
- EN 301 549 9.2.5.3 · RGAA 6.1.5
- Last reviewed
- 16 October 2026