WCAG 2.2 Demo Suite

2.5.3 Level A Guideline 2.5 Input Modalities Added in WCAG 2.1 Partly detectable automatically

Label in Name

For components with a visible text label, the accessible name contains the visible text.

Who this affects

Speech input users who say "click Submit order" — if the accessible name is "Send", the command fails. Screen reader users with some sight hear one thing and see another.

The failure and the fix

Each example below is a self-contained page, loaded in a frame so its markup cannot affect this page. Open either one on its own to test it with a keyboard or screen reader.

Fails 2.5.3

Open the failing example in a new tab

fail.html — the problem

<h1>Your basket</h1>

<!-- FAILURE 1: the visible label says "Place order". The accessible name says
     "Submit". A speech-input user says "click Place order" and nothing happens,
     because the name the software matches against does not contain the words
     on screen. -->
<button type="button" class="button" aria-label="Submit">Place order</button>

<!-- FAILURE 2: aria-label completely replaces the visible text. Note that
     aria-label wins over the element's content, so the visible words are
     simply gone from the accessibility tree. -->
<p><a href="#promo" aria-label="Discounts">Apply a promotion code</a></p>

<!-- FAILURE 3: the accessible name starts with extra words, so it does not
     CONTAIN the visible label as a contiguous string. Extra words are allowed
     by 2.5.3 only if the visible text still appears intact within the name -
     "Go to basket page" does not contain "View basket". -->
<p><a href="#basket" aria-label="Go to basket page">View basket</a></p>

<!-- FAILURE 4: a search field labelled visually as "Search books" but named
     "query" by its title attribute. -->
<div class="field">
  <label for="q">Search books</label>
  <input type="search" id="q" aria-label="query">
</div>

<p id="promo">Promo.</p><p id="basket">Basket.</p>

Meets 2.5.3

Open the passing example in a new tab

pass.html — the fix

<h1>Your basket</h1>

<!-- FIX 1: no aria-label at all. The button's own text becomes its accessible
     name, so the visible label and the name are the same string by
     construction and cannot drift apart. This is the reliable fix. -->
<button type="button" class="button">Place order</button>

<!-- FIX 2: the link text is the name. -->
<p><a href="#promo">Apply a promotion code</a></p>

<!-- FIX 3: if you must extend the name for extra context, the visible text
     must still appear inside it, unbroken - and it should come first, so
     speech commands match on the words the user can actually see. -->
<p><a href="#basket" aria-label="View basket, 2 items">View basket</a></p>

<!-- FIX 4: a real label element. The visible label IS the accessible name. -->
<div class="field">
  <label for="q">Search books</label>
  <input type="search" id="q" name="q">
</div>

<!-- Note: a purely graphical control has no visible text label, so 2.5.3 does
     not apply to it - but 4.1.2 still requires it to have an accessible name. -->

<p id="promo">Promo.</p><p id="basket">Basket.</p>

How to test it

Compare each control's visible text against its accessible name in the accessibility tree. An aria-label that overrides the visible text is the classic failure.

  • Automated

    Scanners compare visible text with the accessible name and catch most mismatches, but cannot always determine the visible label for complex controls.

    This demo's failure is not machine-detectable. axe does have a label-content-name-mismatch rule for exactly this failure, but it is marked EXPERIMENTAL and is therefore switched off in axe's default configuration. A standard scan reports nothing. You have to opt in to experimental rules to see it - and most CI pipelines never do.

    Relevant axe rules:

    • label-content-name-mismatch

  • Keyboard

    Unplug the mouse. Move through the page with Tab, Shift+Tab, Enter, Space and the arrow keys. See the keyboard testing script.

  • Screen reader

    Listen to both examples with NVDA, JAWS, VoiceOver or TalkBack and compare what is announced. See the screen reader cheat sheets.

  • Visual

    Zoom to 200% and 400%, narrow the viewport to 320 px, and apply the text-spacing overrides. See the visual testing procedures.

In the specification