November 30, 2020 · reala11y team

How assistive tech computes an accessible name

label, aria-label, aria-labelledby, alt, title — the accessible name computation decides what a screen reader announces. Here's the order it uses and how to control it.

Every interactive thing on your page — every button, link, input, and image — has an accessible name: the string a screen reader speaks when focus lands on it. “Submit.” “Search the site.” “Home.” If that name is wrong, missing, or unhelpful, the control is effectively unlabelled for anyone not looking at the screen, no matter how obvious it looks visually.

The catch is that the accessible name is computed, not just “the text you see.” Several attributes feed into it, they have a strict priority order, and they override each other in ways that surprise people. Understanding that order is the difference between confidently labelling a control and guessing.

The computation, in priority order

Browsers follow the W3C Accessible Name and Description Computation. For most elements, it walks these sources and stops at the first one that produces a non-empty name:

1. aria-labelledby — points at the id(s) of other elements; their text becomes the name. Highest priority.
2. aria-label — a string you supply directly on the element.
3. The native label mechanism — for a form control, an associated <label>; for an image, the alt attribute; for a button, its text content.
4. title — the tooltip attribute, used only as a last resort.

The headline consequence: aria-label and aria-labelledby win over your visible text. If you put aria-label="Close" on a button that visibly reads “Cancel,” screen-reader users hear “Close” while sighted users see “Cancel” — a mismatch that also fails WCAG 2.5.3 (Label in Name). So override the visible text only when you genuinely mean to.

Form inputs: associate a real label

The single most common naming failure is an unlabelled form field. The robust fix is a <label> tied to the input by for/id:

<label for="email">Email address</label>
<input type="email" id="email" name="email">

Wrapping also works and needs no matching ids:

<label>
  Email address
  <input type="email" name="email">
</label>

What does not work: placing text near an input with no programmatic association. Sighted users infer the relationship from layout; a screen reader cannot. Two more traps:

• Placeholder is not a label. placeholder="Email" disappears on typing and is poorly/inconsistently exposed as a name. Use it for an example format, never as the field’s only label.
• Icon-only fields (a magnifying-glass search box) need aria-label="Search" or a visually hidden <label>, because there’s no visible text to borrow.

Buttons and links

A text button gets its name from its content for free: <button>Save draft</button> announces “Save draft.” The problem is icon-only controls — a hamburger menu, an × close, a bare SVG. Visually clear, audibly empty.

<!-- Bad: announces "button", no name -->
<button><svg>…</svg></button>

<!-- Good: explicit name -->
<button aria-label="Close dialog"><svg aria-hidden="true">…</svg></button>

Note aria-hidden="true" on the inner SVG so its contents don’t leak into the name. For links, the same applies — and beware generic link text. “Read more” repeated twelve times gives a screen-reader user twelve identical names in their links list. Make the visible text descriptive, or extend it with a visually hidden span:

<a href="/2020/wcag-2-2/">Read more<span class="screen-reader-text"> about WCAG 2.2 changes</span></a>

Images: alt is the name

For an <img>, the alt attribute is the accessible name. Three cases:

• Informative image: describe its meaning concisely. alt="Bar chart: traffic doubled in Q3".
• Decorative image: use an empty alt="" so the screen reader skips it. Omitting alt entirely is different — some screen readers then read the filename, which is worse than nothing.
• Image inside a link with no other text: the alt becomes the link’s name, so describe the destination, e.g. alt="reala11y home".

Why title is a trap, not a tool

title sits at the bottom of the priority list for a reason. It only appears on mouse hover, never on keyboard focus or touch, and screen-reader support for it is inconsistent. Relying on title to name a control means keyboard and touch users get nothing. Worse, a redundant title on an image (often auto-added by WordPress from the media title) just produces a duplicate tooltip and noise — which is why reala11y’s optional fixer F022 strips title attributes from images in post content. Use a real label instead.

Testing what you actually shipped

Two quick checks:

1. Browser DevTools accessibility pane. Inspect an element; Chrome and Firefox show the computed accessible name and which source it came from. This is the fastest way to confirm aria-labelledby resolved correctly.
2. A screen reader. Tab through your forms and toolbars with NVDA or VoiceOver and listen. If a control announces only its role (“button,” “edit”) with no name, it needs one.

The honest takeaway

The accessible name is the most fundamental piece of information assistive tech exposes, and it follows rules you can learn in an afternoon: aria-labelledby, then aria-label, then the native label or alt, then title as a grudging fallback. Prefer a real, visible <label> and descriptive link text; reserve aria-label for the icon-only cases that have no visible text to use. Automated tools reliably catch the blatant misses — a button with no name, an input with no label — and that’s worth running, but they detect only ~30–40% of WCAG issues by criteria and can’t judge whether a name is accurate. So fix the obvious gaps with a scanner, then put on a screen reader and listen to what your controls actually say. That pairing moves you toward WCAG 2.2 AA conformance — the only claim worth making, since no tool earns it for you.