Links and buttons Rule

The words on a control must be part of its accessible name label-content-name-mismatch

People who use voice control activate a control by saying the words they can see on it. If the control carries an aria-label that says something else, the words they say do not match the name the software knows, and nothing happens. Make the accessible name start with the visible text, then add detail after it if you need to.

WCAG 2.2 A 2.5.3 Label in Name

Websight reports this as Elements must have their visible text as part of their accessible name

Who it affects

Someone with a repetitive strain injury, using Dragon to book theatre tickets says 'click Book now' and nothing happens, because the button's hidden name is 'Purchase tickets'.

Someone with low vision who uses a screen reader alongside the screen hears a different name from the one they can read, and is not sure it is the same button.

Someone with a cognitive disability following written instructions is told to press Book now, but the voice assistant and help pages built from the accessible names call it something else.

Broken versus fixed

Both examples are live and rendered in a sandboxed frame. The broken one is deliberately broken.

Broken

The screen says Book now. The accessible name says Purchase tickets. Saying 'click Book now' does nothing.

Fixed

The name starts with the visible words, so 'click Book now' works, and a screen reader also hears which show it books.

Show the markup behind both examples
Broken
<style>body{font-family:system-ui;margin:0;padding:16px}.show{display:flex;gap:12px;align-items:center;justify-content:space-between;max-width:360px;border:1px solid #d0d7de;border-radius:8px;padding:12px}button{background:#8a1c2b;color:#fff;border:0;border-radius:6px;padding:8px 14px;font-size:15px;cursor:pointer}</style>
<div class="show">
  <span><strong>Hamlet</strong><br>Saturday 7.30pm</span>
  <button aria-label="Purchase tickets">Book now</button>
</div>
Fixed
<style>body{font-family:system-ui;margin:0;padding:16px}.show{display:flex;gap:12px;align-items:center;justify-content:space-between;max-width:360px;border:1px solid #d0d7de;border-radius:8px;padding:12px}button{background:#8a1c2b;color:#fff;border:0;border-radius:6px;padding:8px 14px;font-size:15px;cursor:pointer}</style>
<div class="show">
  <span><strong>Hamlet</strong><br>Saturday 7.30pm</span>
  <button aria-label="Book now for Hamlet, Saturday 7.30pm">Book now</button>
</div>

Test it by hand in two minutes

  1. In Chrome DevTools, select the control and open the Accessibility pane. Compare the computed Name with the words you can see. The visible words should appear in the name, in the same order.
  2. On a Mac, turn on Voice Control (System Settings, Accessibility) and say 'click' followed by the words on the button. On Windows, try Voice Access. If nothing happens, the name does not match.
  3. Search the page source for aria-label on elements that also have visible text. Each one is a candidate for this problem.

The fix

Before
<button aria-label="Purchase tickets">Book now</button>
After
<button aria-label="Book now for Hamlet, Saturday 7.30pm">Book now</button>

Often the right fix is to delete the aria-label and let the visible text be the name. Add a label only when you need extra context, and start it with the visible words.

Read more link with a different label

Before
<a href="/whats-on/hamlet" aria-label="Hamlet details">Read more</a>
After
<a href="/whats-on/hamlet" aria-label="Read more about Hamlet">Read more</a>

Keep the visible words first, then say what the link is about.

Label that describes the icon rather than the text

Before
<button aria-label="Shopping bag">Basket</button>
After
<button>Basket</button>

The visible text was already a good name. Remove the label.

Common mistakes

  • Rewriting the aria-label to be 'clearer' than the visible text instead of extending it.
  • Writing the aria-label in a different language from the visible text.
  • Putting the real name in aria-label and leaving the visible text as a vague placeholder.
  • Pointing aria-labelledby at a heading when the control has its own text; the text is then dropped from the name.

WCAG criteria this rule maps to

axe-core tags this rule as WCAG 2.2 level A. It is one of the checks for:

The scanner compares the visible text of buttons, links and similar controls with their accessible name and flags any where the visible words are not in the name. It ignores symbols and punctuation. It cannot see words drawn in images. Automated tools find only part of the accessibility problems on a page; a pass on this rule is not a pass on the criterion.

A Links must have text a screen reader can announce link-name Every link needs text that a screen reader can announce and a voice control user can say. A ARIA buttons, links and menu items need a name aria-command-name When you give an element role="button", role="link" or role="menuitem", you are promising assistive technology that it is a control.

Scan your own page for this and 63 other checks

Open any page in Chrome, click Websight, and get a score out of 100 with every issue explained and a draft fix snippet per element.

Add Websight to Chrome

Free scans, no account, nothing leaves your computer. Automated tools find only part of the problems; the extension says so on every report.