Visible text ≠ accessible name
label-in-name/mismatch
- WCAG success criterion
- 2.5.3 (level A)
- Outcome class
- Automatic. An automated check that can report a confirmed violation.
- Area
- Accessibility, Navigation & Operation
- Default severity
- high
- axe-core rule
label-in-name
Why we flag this
Voice-control users cannot address the element.
aria-label diverges from the visible text.
What the rule checks
Scope. Elements with a name-from-content role (button, link, checkbox, menuitem, tab, ...) whose name is authored (aria-label, aria-labelledby) and whose rendered text contains letters (Rendered scope: text under aria-hidden is still visible).
Expectation. Fails when the accessible name does not contain the visible label (case, punctuation and spacing ignored): saying "Play" does not activate a button named "Start stream". A name that is only part of a short visible label also fails ("Pricing" for "Pricing plans"). When the visible text is more than twice as long as the name, or only reorders its words, the visible label of a composite widget is ambiguous: review. A name that contains the label passes, as does a symbol-only label (footnote ¹). Elements not rendered are out of scope.
Source. WCAG 2.2 SC 2.5.3 Label in Name; Understanding 2.5.3 (symbolic labels excepted)
Detection: shared; needs dom, ax_tree.
Failing example
The check reports a violation here. Corpus case aria_shared_deviations, element a#pricing-link. The page may contain further findings for other rules.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>File manager - Example cloud</title>
</head>
<body>
<header>
<p>Example cloud</p>
</header>
<main>
<h1>Your files</h1>
<!-- Role fallback list: the first token is unknown, the second a
valid role; user agents use the first valid token (WAI-ARIA 1.2,
section 7.1). ACT 674b10 passes it. -->
<div id="upload" role="upload button" tabindex="0">Upload</div>
<!-- Name is part of the visible label but does not contain it:
speaking "Pricing plans" does not match the name "Pricing"
(WCAG 2.5.3). -->
<a href="/pricing" id="pricing-link" aria-label="Pricing">Pricing plans</a>
<!-- A tree needs a name (WAI-ARIA 1.2, tree: accessible name
required). -->
<ul id="folders" role="tree">
<li role="treeitem" id="folder-docs" tabindex="0" aria-selected="true">Documents</li>
<li role="treeitem" id="folder-photos" tabindex="-1" aria-selected="false">Photos</li>
</ul>
</main>
<footer>
<p>Example cloud</p>
</footer>
</body>
</html>Passing example
The check passes here and reports nothing. Corpus case aria_names_valid. The page may contain further findings for other rules.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Media player - Example radio</title>
</head>
<body>
<header>
<p>Example radio</p>
</header>
<main>
<h1>Live stream</h1>
<!-- Every alternative name source: aria-label, aria-labelledby,
<label>, title on a native field, content -->
<div id="volume" role="slider" tabindex="0" aria-label="Volume" aria-valuenow="7" aria-valuemin="0" aria-valuemax="10"></div>
<div id="autoplay" role="switch" tabindex="0" aria-checked="false" aria-labelledby="autoplay-label"></div>
<span id="autoplay-label">Autoplay</span>
<label for="station">Station</label>
<input id="station" type="text">
<input id="search" type="search" title="Search stations">
<div id="genre" role="radiogroup" aria-label="Genre">
<div role="radio" id="genre-jazz" tabindex="0" aria-checked="true">Jazz</div>
<div role="radio" id="genre-pop" tabindex="-1" aria-checked="false">Pop</div>
</div>
<!-- One-character names that are letters or digits, and a symbol
from content rather than from an attribute -->
<button type="button" id="channel-1" aria-label="1">1</button>
<button type="button" id="umlaut" aria-label="Ä">Ä</button>
<button type="button" id="next-arrow">→</button>
<!-- Title only adds to a visible name -->
<button type="button" id="share" title="Opens the share dialog">Share</button>
<!-- Name contains the visible label; a symbol label is exempt -->
<button type="button" id="play" aria-label="Play live stream">Play</button>
<a href="/notes#fn1" id="fn-ref" aria-label="Footnote 1"><sup>¹</sup></a>
<!-- Description adds information beyond the name -->
<button type="button" id="mute" aria-describedby="mute-desc">Mute</button>
<span id="mute-desc" hidden>Silences the stream until you unmute it</span>
<!-- Named summary, also through aria-label on an icon-only summary -->
<details id="lyrics">
<summary id="lyrics-summary">Lyrics</summary>
<p>No lyrics available.</p>
</details>
<details id="credits">
<summary id="credits-summary" aria-label="Credits"><span aria-hidden="true">ℹ</span></summary>
<p>Produced by Example radio.</p>
</details>
<!-- SVGs: named by title, by aria-label, decorative, and an icon inside
a named button -->
<svg id="cover" role="img" width="120" height="120" viewBox="0 0 120 120">
<title>Album cover: Blue Nights</title>
<rect width="120" height="120" fill="#335"></rect>
</svg>
<svg id="logo" role="img" aria-label="Example radio logo" width="40" height="40"><circle cx="20" cy="20" r="18"></circle></svg>
<svg id="divider" role="presentation" width="200" height="4"><path d="M0 2 L200 2" stroke="#000"></path></svg>
<button type="button" id="like"><svg id="like-icon" width="16" height="16"><circle cx="8" cy="8" r="6"></circle></svg> Like</button>
</main>
<footer>
<p>Example radio</p>
</footer>
</body>
</html>This page is generated from the rule catalogue and the rule contracts; see therule overview for how the outcome classes are derived.