Fixing ARIA Labels and Accessible Names

How a browser decides what a control is called

Browsers build an accessibility tree alongside the page, and each interactive element in it gets a role (button, link, textbox) and a name. WCAG 4.1.2, Name, Role, Value, at level A, requires that every user interface component has a name that assistive technology can read. The rules the browser follows are set out in the W3C's Accessible Name and Description Computation specification. In simplified form, the first of these that exists wins:

1. aria-labelledby: the text of the element or elements whose IDs it lists.
2. aria-label: the string in the attribute.
3. Native labelling: a connected <label> for a form field, alt for an image, <caption> for a table, <legend> for a fieldset.
4. Content: for buttons, links and some other roles, the text inside the element, including the alt of any image in it.
5. title: a last resort, and a weak one.

Two consequences surprise people. First, ARIA overrides what is on screen: a button showing "Buy now" with aria-label="Add to cart" is announced as "Add to cart". Second, ARIA changes only what assistive technology is told. It does not add keyboard behaviour, focus or visible text. That is why the first rule of ARIA, as the W3C puts it, is to use a native HTML element with the semantics you need wherever one exists.

The ARIA findings you are most likely to see

Button or link has no accessible name

The most common and most serious. A hamburger menu, a close cross, a social icon or a slider arrow built from an SVG or icon font, with no text inside. A screen reader says only "button", and a voice control user has nothing to say to press it.

<!-- Fails: nothing to announce -->
<button class="menu-toggle"><svg viewBox="0 0 24 24">...</svg></button>

<!-- Fixed -->
<button class="menu-toggle" aria-expanded="false" aria-controls="main-menu" aria-label="Menu">
  <svg aria-hidden="true" focusable="false" viewBox="0 0 24 24">...</svg>
</button>

Accessible name does not contain the visible label

WCAG 2.5.3, Label in Name, at level A, requires that when a control has visible text, its accessible name includes that text, ideally at the start. A voice control user looks at a button labelled "Send" and says "click Send". If the code says aria-label="Submit enquiry form", the command fails. The simplest fix is usually to delete the aria-label and let the visible text be the name.

aria-labelledby points at an ID that does not exist

The attribute takes one or more IDs separated by spaces. If an ID is misspelt, was changed in a redesign, or is duplicated on the page, the name comes out empty or wrong. Components rendered more than once, such as a product card or an accordion, are a frequent cause, because hard-coded IDs repeat.

aria-hidden element is focusable

If something is hidden from the accessibility tree but can still receive keyboard focus, a screen reader user tabs to it and hears silence or a confusing fragment. It often happens with off-screen menus, closed modals and carousel slides that are hidden with aria-hidden="true" but still contain links.

aria-label used where it is not supported

ARIA names are prohibited on generic elements. An aria-label on a plain <div>, <span> or <p> with no role is ignored by many screen readers, so the text never reaches the user. If the text matters, make it visible; if the element needs a name, it probably needs a proper role or element first.

The fix, step by step

Correct patterns you can copy

A section named by its visible heading

<section aria-labelledby="delivery-heading">
  <h2 id="delivery-heading">Delivery and returns</h2>
  ...
</section>

A <section> only becomes a region landmark when it has a name, and reusing the heading keeps the name and the visible text in step.

Two navigation areas told apart

<nav aria-label="Main">...</nav>
<nav aria-label="Footer">...</nav>

Screen readers already say "navigation", so the label is just "Main" or "Footer", not "Main navigation".

A visually hidden name that translates

<a href="/basket" class="basket-link">
  <svg aria-hidden="true" focusable="false">...</svg>
  <span class="visually-hidden">Basket</span>
  <span class="count">2</span>
</a>

.visually-hidden {
  position: absolute; width: 1px; height: 1px;
  margin: -1px; padding: 0; overflow: hidden;
  clip: rect(0 0 0 0); white-space: nowrap; border: 0;
}

Some automatic translation tools translate page text but not attribute values, so a visually hidden span is often a safer choice than aria-label on multilingual sites.

A dialog named by its title and described by its text

<div role="dialog" aria-modal="true" aria-labelledby="dlg-title" aria-describedby="dlg-desc">
  <h2 id="dlg-title">Remove item?</h2>
  <p id="dlg-desc">The blue kettle will be removed from your basket.</p>
  <button type="button">Remove</button>
  <button type="button">Keep it</button>
</div>

The native <dialog> element opened with showModal() is now well supported and handles focus containment for you; the labelling works the same way.

ARIA mistakes that make things worse

Where ARIA problems come from

WordPress. Menu toggles, search icons and social icon blocks in themes and page builders are the usual sources. Block themes generally output labelled navigation toggles; older themes and builder widgets may not. Many builders offer an "ARIA label" or "accessible name" field on icon and button widgets. Where they do not, a child theme template override is the durable fix.

Shopify. Themes provide most icon buttons, such as the cart, account and search icons in the header and the slider controls in product galleries. Their labels often come from the theme's translation strings in the locale files, so a missing label may be an empty translation rather than missing markup. Check apps that inject chat buttons, review stars and pop-ups too.

React, Vue and other frameworks. Component libraries usually label their own controls, but custom icon buttons are often written without a name. Make the name a required prop on your IconButton component, generate IDs with the framework's ID helper, and use the eslint-plugin-jsx-a11y rules, or the equivalent for your framework, to catch missing names and invalid ARIA while coding. For wider framework advice see the React and Next.js accessibility guide.

Keeping accessible names correct

1. Prefer visible text. A button that says "Download brochure" needs no ARIA at all and helps every visitor.
2. Build one icon button component that cannot be used without a name, and use it everywhere.
3. Review aria-label values whenever visible text changes, so the two do not drift apart.
4. Run automated checks in development and the Accessibility Audit after each release.
5. Include a quick screen reader pass in testing for any new interactive component, such as a menu, tab set or modal.

ARIA naming overlaps with two other guides: form fields are covered in fixing form labels, and links whose visible text is vague are covered in fixing vague link text. Controls you cannot reach at all belong in fixing keyboard navigation.