
WCAG 2.5.3 Label in Name: Fix Accessible Name Mismatches
WCAG 2.5.3 fails when a button or link's aria-label doesn't contain its visible text. Here's why it breaks voice control and exactly how to fix it.
WCAG 2.5.3 (Label in Name) requires that when a button or link has visible text, that same text must appear inside its accessible name. The most common violation is a control whose visible text says one thing while its aria-label says something else entirely — voice control software can't match the two, so the command fails.
What does WCAG 2.5.3 Label in Name actually require?
WCAG 2.5.3 is a Level A success criterion under the Input Modalities guideline. The official wording: "For user interface components with labels that include text or images of text, the name contains the text that is presented visually."
In plain terms: if a user can see words on a button or link, those same words need to be part of what a screen reader or voice assistant calls that control. The accessible name doesn't have to match the visible text exactly, word for word — but the visible text has to appear inside it, as a substring, case-insensitive.
This rule exists for one specific group: people using speech-recognition software like Dragon NaturallySpeaking, or built-in voice control on iOS and macOS. These tools work by matching what a user says against the visible label on screen. Say "click submit," and the software looks for a control named something containing "submit." If the underlying accessible name is actually "Send your information now," the match fails and the command does nothing.
Why does this error happen in the first place?
It almost always comes down to aria-label quietly overriding visible text. Per the accessible name computation rules, an aria-label attribute takes priority over any text content inside the element. So a developer can write:
<a href="/products" aria-label="View our full product catalog">Shop</a>
Sighted keyboard users and screen reader users relying only on the visible word "Shop" never notice a problem. But the computed accessible name is "View our full product catalog" — and "Shop" never shows up in it. That's a Label in Name failure, even though the link is perfectly readable and perfectly functional for most people.
This is different from an icon-only button that has no visible text at all. Those controls need an accessible name from somewhere — an aria-label, hidden text, whatever — because there's nothing visible to compare against. That's a separate (and very common) failure covered in this guide to icon-only buttons. Label in Name only applies when a control already has visible text and the aria-label contradicts or replaces it.
Rewritten labels show up most often in a few predictable places:
- "Learn more" or "Read more" links where a developer adds
aria-labelto give screen reader users more context, but phrases it completely differently from the visible text - Buttons generated by component libraries or CMS themes where the label text and the
aria-labelcome from two different data fields - Call-to-action buttons where marketing copy says "Get Started" but an accessibility retrofit added
aria-label="Start your free trial"without checking for overlap - Translated or localized sites where the visible string and the
aria-labelstring were translated independently and drifted apart
How do I check if my buttons and links pass Label in Name?
Run this test on every interactive control with visible text: read the visible label, then check the accessible name computed by the browser. You can do this in Chrome or Edge DevTools by selecting an element, opening the Accessibility pane, and reading the "Name" field — or by inspecting with a screen reader like NVDA or VoiceOver and listening to what it announces.
Ask one question for each control: does the visible text appear, word for word, somewhere inside the announced name? If the answer is no, you have a Label in Name failure. Case doesn't matter — "SUBMIT" matches "submit" — but the actual words need to be present, not paraphrased or replaced.
A scanner can automate most of this check by comparing the DOM's visible text node against the computed accessible name for every link and button. That's exactly what AccessKnight's free scanner looks for when it flags this rule, alongside the other 32 automated WCAG checks it runs on any public URL.
How do I fix "visible label is not part of accessible name"?
There are two ways to fix this, and one of them is usually better than the other.
Option 1: Remove the aria-label entirely
If the visible text already says what the control does, you don't need an aria-label at all. This is the simplest, most reliable fix:
<!-- Before: fails 2.5.3 -->
<a href="/products" aria-label="View our full product catalog">Shop</a>
<!-- After: passes, visible text is the accessible name -->
<a href="/products">Shop</a>
Less markup, no mismatch, nothing to keep in sync later when someone edits the button copy and forgets the label attribute exists.
Option 2: Rewrite the aria-label to include the visible text
Sometimes you genuinely need extra context in the accessible name — for example, several "Edit" buttons on a page that all need to announce which row they belong to. In that case, put the visible text at or near the start of the aria-label:
<!-- Before: fails, "Edit" is nowhere in the aria-label -->
<button aria-label="Modify invoice #4521">Edit</button>
<!-- After: passes, visible word "Edit" is contained in the name -->
<button aria-label="Edit invoice #4521">Edit</button>
Same fix applies to links:
<!-- Before: fails -->
<a href="/blog/post-1" aria-label="Continue reading about accessibility law">Read more</a>
<!-- After: passes -->
<a href="/blog/post-1" aria-label="Read more about accessibility law">Read more</a>
Notice the pattern: the visible words come first, then the extra context gets appended after. That's not a strict requirement of the success criterion, but it's the safest approach because some voice control tools match more reliably when the visible phrase sits at the start of the name rather than buried in the middle.
If you're dealing with generic link text like "click here" or "read more" that's vague even before you consider accessible names, that's really a separate problem worth fixing on its own — see the guide on rewriting generic link text for how to make link purpose clear without relying on aria-label at all.
What about aria-labelledby?
aria-labelledby has the same effect as aria-label in the accessible name computation — it overrides visible text content. If a button references a hidden <span> for its labelledby source, that referenced text needs to contain the visible label too. The fix is the same principle: make sure whatever text ends up in the computed name includes the words a sighted user actually sees on the button.
Does this affect voice control users more than screen reader users?
Yes, mostly. Screen reader users hear the accessible name read aloud regardless of what's visible, so a mismatched label is confusing but not necessarily blocking — they'll hear "View our full product catalog" and can still activate the link. Voice control users have a harder problem: their software listens for the visible word and searches for a matching accessible name. If the words don't overlap, the command simply does nothing, with no error message explaining why.
That said, mismatched labels cause a secondary problem for screen reader users too: when a screen reader user and a sighted colleague are talking about "the Shop button" on a call, and the screen reader actually announces "View our full product catalog," that's a confusing disconnect that makes collaborative troubleshooting harder. Consistency between what's seen and what's announced isn't just a technical checkbox — it keeps the page predictable for everyone describing it.
How does Label in Name fit with other accessible-name rules?
WCAG 2.5.3 is narrowly about consistency between visible and accessible text — it assumes a name already exists. It's worth distinguishing from two related but separate checks:
- WCAG 4.1.2 (Name, Role, Value) requires that every control has some accessible name at all. A button with no text and no
aria-labelfails this regardless of Label in Name. See the guide on buttons with no accessible name for that failure mode. - WCAG 2.5.3 (Label in Name) requires that when a name does exist and visible text also exists, the two aren't contradictory.
You can pass 4.1.2 and still fail 2.5.3 — a button can have a perfectly valid accessible name that just doesn't match what's printed on it. Both checks matter, and both show up in a full WCAG rule-by-rule audit.
Frequently Asked Questions
What is WCAG 2.5.3 Label in Name?
WCAG 2.5.3 is a Level A success criterion requiring that any visible text label on a button, link, or other control also appears within that control's programmatically determined accessible name. It exists mainly to support speech-recognition and voice control software, which matches spoken commands against visible labels.
Why does an aria-label override visible button text?
Per the accessible name computation algorithm, aria-label takes precedence over any text content inside an element. If you add aria-label="Submit your application" to a button that visibly says "Submit," screen readers and voice tools use the aria-label value, not the visible word, as the control's name.
How do I fix "visible label is not part of accessible name"?
Either remove the aria-label so the visible text becomes the accessible name by default, or rewrite the aria-label so it contains the exact visible text, ideally at the start of the string. Both approaches satisfy WCAG 2.5.3 as long as the visible words appear somewhere in the computed name.
Does Label in Name apply to icon-only buttons with no visible text?
No. WCAG 2.5.3 only applies when a control has visible text to compare against. An icon-only button with no text relies entirely on aria-label for its name, which is a different requirement under WCAG 4.1.2 (Name, Role, Value).
Does capitalization or punctuation matter for Label in Name compliance?
Capitalization doesn't matter — the comparison is case-insensitive, so "SUBMIT" and "submit" match fine. Extra punctuation or surrounding words in the accessible name are also fine, as long as the exact visible text appears somewhere within it.
Is WCAG 2.5.3 Level A or Level AA?
Label in Name is a Level A success criterion, which means it's part of the baseline conformance level required under ADA Title II's WCAG 2.1 AA requirement for state and local government websites, since AA conformance includes every Level A criterion as well.
Next step
Open your site's most important buttons and links in DevTools and check the computed "Name" field against what's printed on screen — pay particular attention to anywhere a developer added aria-label for "extra context." That's where mismatches hide. Or run a free scan at AccessKnight and it'll flag every Label in Name mismatch on the page automatically, with the exact line of markup to fix.
Fix guides for this topic
Step-by-step fixes with copy-paste code for the checks this article covers.
- Buttons with no accessible nameWCAG 4.1.2 · Level AW3C: Understanding 4.1.2
- Links with no accessible nameWCAG 2.4.4 · Level AW3C: Understanding 2.4.4
- Interactive elements with no readable nameAI readability
- Invalid or misspelled ARIA attributesWCAG 4.1.2 · Level AW3C: Understanding 4.1.2
Check your website's accessibility
Scan against all 33 WCAG 2.1 rules and get code-level fix suggestions — free.
Run a free scan →