Accessible Name Must Match Visible Text: How to Fix It

This check flags controls whose accessible name does not contain the words a sighted user actually reads on the button or link. When the visible label and the programmatic name drift apart, voice-control users who say “click Submit order” get nothing, and screen-reader users hear one label while everyone else sees another — a direct failure of WCAG 2.5.3 Label in Name.

What “label in name” actually means

Every interactive control has two labels. One is the visible text painted on screen. The other is the accessible name that assistive tech computes — usually from that same text, but an aria-label, aria-labelledby, or title can override it. WCAG 2.5.3 says the accessible name must contain the visible label text, in the same order, so that speech-input users can activate a control by speaking what they see.

The classic trap is a designer writing “Submit” on a button but a developer bolting on aria-label="Send your order now" for “extra context.” The word “Submit” has vanished from the accessible name. Say “Submit” to Dragon or Voice Control and the command dies. That mismatch is what the checker catches.

A real failing pattern and the fix

<!-- FAILING: visible text "Add to cart", accessible name "Buy" -->
<button aria-label="Buy">Add to cart</button>

<!-- FAILING: icon + visible word, but label omits the word -->
<a href="/account" aria-label="Profile">
  <svg aria-hidden="true"></svg> My Account
</a>

<!-- FIXED: accessible name starts with the visible words -->
<button>Add to cart</button>

<!-- If you need extra context, keep the visible words first -->
<a href="/account" aria-label="My Account settings">
  <svg aria-hidden="true"></svg> My Account
</a>

The second fix works because “My Account” is still the leading substring of the accessible name. Voice users saying “My Account” land on it, and the trailing “settings” is a bonus, not a blocker.

Where the visible text lives vs. where the name comes from

How to detect it on your own site

1. axe DevTools: open Chrome DevTools, run an axe scan, and look for the rule “label-content-name-mismatch”. It lists every control where the visible text is not part of the accessible name, with the selector.
2. Lighthouse: run the Accessibility audit; the “Elements with visible text labels have matching accessible names” item fails and names the offending nodes.
3. WAVE: load the WAVE browser extension, then use the Order or details panel to inspect ARIA. Anywhere an aria-label icon sits over a control that also shows text, hover it and compare the two strings by eye.
4. Manual spot check: in the browser inspector, select a control and read the Accessibility pane’s “Name” value. If the on-screen words are not a leading substring of it, you have a mismatch.

How to fix it

1. Delete the aria-label or aria-labelledby entirely when the visible text already describes the control — the native text becomes the accessible name and they can never diverge.
2. If you genuinely need a longer name, rewrite it so the visible words come first: aria-label="Add to cart – 2 items", not aria-label="Cart".
3. For icon-plus-text controls, hide the icon with aria-hidden="true" and let the visible word be the name; don’t re-label the whole control.
4. Watch punctuation and casing loosely — the check ignores case and trims symbols, but it will not forgive a wholesale word swap.
5. Re-scan with axe after each change; the label-content-name-mismatch count should drop to zero.

Why it matters beyond passing a scan

Voice control is the population that gets burned hardest here. Someone using their hands very little navigates by speaking visible labels; a mismatch means a control they can clearly see is one they cannot operate. Screen-reader users hit a subtler version — the name announced doesn’t match what a sighted colleague describes over the phone, so collaboration breaks. And because search crawlers lean on accessible names to understand link and button purpose, clean, honest labels help machines parse your interface too. Related discernible-text failures on buttons and links compound the damage when they appear together.

FAQ

Does the accessible name have to match the visible text exactly?

No. It has to contain the visible text as a substring, in order. “Search the catalog” passes for a button reading “Search” because the visible word appears first. A total swap like “Go” for “Search” fails.

What if my visible text is just an icon with no words?

Then there’s no visible text to match, and 2.5.3 doesn’t apply — but you still owe the control an accessible name. That’s the separate “discernible text” requirement covered on the buttons must have discernible text check.

Can I keep extra context for screen readers?

Yes, as long as the visible words lead the accessible name. Put the on-screen label first and append the extra detail: aria-label="Download report (PDF, 2 MB)" for a link reading “Download report”.

Does a title attribute cause this failure?

Rarely, because title sits low in the accessible-name computation — visible text usually wins. The failure almost always traces back to aria-label or aria-labelledby overriding the on-screen words.

Is this a WCAG A or AA requirement?

Label in Name (2.5.3) is a Level AA success criterion, so it’s in scope for the vast majority of legal and procurement accessibility targets. It pairs closely with correct ARIA roles in giving every control an honest identity.