Visible Label and Name Matching

When a user interface control has a visible text label, assistive technologies also expose a programmatic name (the accessible name) to the operating system and to tools like screen readers or voice control software. Visible label and name matching is the principle that the accessible name must include the visible label text. If the two diverge, a speech input user who says "click Submit" will fail to activate a button whose accessible name is actually "Send form data," even though the button visually reads "Submit."

This requirement is codified in WCAG 2.1 Success Criterion 2.5.3 (Label in Name), at Level A. The criterion states: "For user interface components with labels that include text or images of text, the name contains the text that is presented visually." The word "contains" is deliberate. The accessible name may be longer than the visible text, but it must include the visible text as a substring, and ideally the visible text should appear at the start of the accessible name.

Why visible label and name matching matters

Speech input users interact with web pages by speaking the visible text of a control. Dragon NaturallySpeaking, Windows Voice Access, and Apple Voice Control all rely on matching spoken words to accessible names. When the accessible name does not contain the visible label, the voice command fails silently, and the user has no obvious way to activate the control.

Screen reader users face a different but related problem. If a sighted colleague tells them "click the Search button," but the screen reader announces "Find items," the two people are effectively looking at different interfaces. Cognitive load rises, and collaboration breaks down.

People with cognitive disabilities also benefit from consistency between what they see and what assistive technology reports. Mismatched labels create confusion that is easy to prevent.

How visible label and name matching works

The accessible name of a control is computed through a well defined algorithm (the accessible name computation). Several HTML mechanisms feed into it, and each one can introduce a mismatch with the visible label.

Sources of mismatch

The most common cause is an aria-label or aria-labelledby attribute that replaces or overrides the visible text. Because aria-label takes precedence over the element's text content in the name computation, a developer can accidentally hide the visible label from the accessible name entirely.

A second cause is the title attribute used as the sole accessible name when no other labeling mechanism is present. If the title text differs from visible text nearby, the names diverge.

A third cause is a <label> element that is programmatically associated with a form control but contains different text than what appears visually, sometimes because CSS hides part of the label or because an icon font replaces readable text.

Rules for correct matching

1. The accessible name must contain the full visible label text as a contiguous substring.
2. The visible text should appear at the beginning of the accessible name when possible, because some speech input tools match from the start of the string.
3. Letter casing differences do not cause failures; the match is case insensitive in assistive technology matching algorithms.
4. Punctuation-only differences (such as a trailing colon visible on screen but absent in aria-label) generally do not cause failures, but keeping punctuation consistent avoids edge cases.

Checking compliance

Browser developer tools expose the computed accessible name in the accessibility tree inspector. Automated tools like axe-core and Rocket Validator flag controls where the visible text is not found within the accessible name. Manual testing with voice control software is the most reliable verification method.

Code examples

Bad example: aria-label replaces visible text

<button aria-label="Send form data">
  Submit
</button>

The button visually reads "Submit," but the accessible name is "Send form data." A speech input user who says "click Submit" will not match this control.

Good example: aria-label contains visible text

<button aria-label="Submit registration form">
  Submit
</button>

The accessible name "Submit registration form" contains the visible text "Submit" at the start of the string, so speech input and screen readers both work as expected.

Bad example: aria-labelledby points to hidden text only

<span id="secret-label" class="visually-hidden">Find items</span>
<button aria-labelledby="secret-label">
  Search
</button>

The visible text is "Search," but the accessible name is "Find items." The two do not match.

Good example: aria-labelledby includes the visible text element

<span id="visible-label">Search</span>
<span id="extra-context" class="visually-hidden">the product catalog</span>
<button aria-labelledby="visible-label extra-context">
  Search
</button>

The accessible name becomes "Search the product catalog," which starts with the visible text "Search." Both speech input and screen readers work correctly.

Bad example: form label text differs from visible text

<label for="email-field" class="visually-hidden">Electronic mail address</label>
<span>Email</span>
<input id="email-field" type="email">

The visible text near the input is "Email," but the accessible name is "Electronic mail address." These do not match.

Good example: form label matches visible text

<label for="email-field">Email</label>
<input id="email-field" type="email">

The <label> element is both the visible text and the source of the accessible name, so they are always in sync. This is the simplest and most reliable pattern.