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 it affects, and how much
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

Business & product impact, with how much each claim weighs
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”

<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”

<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 min

Checklist

Step 1: Press ⌘ F5 to turn VoiceOver on.
Step 2: Press Tab to move through each button and link.
Step 3: Compare what you hear with the words on screen.

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
Read more: Deque University: label-content-name-mismatch (opens in a new tab)
Last reviewed: 16 October 2026