aria-label Not Working on a Div or Button? Why, and How to Fix It

What aria-label actually does

Every interactive element and many structural ones have an accessible name, the text a screen reader speaks and a voice control user says to activate it. Browsers work the name out in a fixed order and use the first source they find:

1. aria-labelledby, pointing at the id of other elements.
2. aria-label, a text string on the element itself.
3. The native source: the <label> of a form field, the alt of an image, the <legend> of a fieldset, the <caption> of a table.
4. The element's own text content, but only for roles that take their name from content, such as buttons, links, headings and table cells.
5. The title attribute or a placeholder, as a last resort.

Two consequences explain most problems. First, aria-label replaces anything lower in the list, so a button with visible text Buy and aria-label="Add to basket" is announced as Add to basket. Second, aria-label is invisible. It never draws anything on screen and it is not a tooltip, which is why people ask why it is not showing.

Why aria-label is ignored

Where it works reliably: buttons, links with an href, form fields, images and SVGs with role="img", landmarks such as <nav>, <section> and <form>, dialogs, and any element given a role that supports a name, such as button, group, region or img.

How to see what the browser is announcing

Do not guess from the source. Ask the browser what name it calculated.

• Chrome or Edge. Right-click the element, choose Inspect, then open the Accessibility pane next to Styles. Under Computed Properties, Name shows the final name and lists each source, with the ones that lost crossed out. Role shows whether the element is generic.
• Firefox. Right-click and choose Inspect Accessibility Properties. Elements that do not appear in the tree at all are being ignored.

To list every aria-label on a page and the role of its element, paste this into the console:

document.querySelectorAll('[aria-label]').forEach(el => {
  const role = el.getAttribute('role') || el.tagName.toLowerCase();
  const hidden = el.closest('[aria-hidden="true"]') ? ' (inside aria-hidden)' : '';
  console.log(role, '|', el.getAttribute('aria-label') + hidden);
});

Anything listed as div, span, p or a without an href is a candidate for the fixes below. Then confirm with a real screen reader: NVDA is free on Windows, Narrator is built in (Ctrl+Windows+Enter), and VoiceOver is built into Mac and iPhone.

The fixes in code

A clickable div with aria-label

Swap it for a real button. You get the role, keyboard support and focus for free, and the label then works:

<!-- Before: not announced, not focusable -->
<div class="close" aria-label="Close" onclick="closeMenu()"><svg>...</svg></div>

<!-- After -->
<button type="button" class="close" aria-label="Close menu">
  <svg aria-hidden="true" focusable="false">...</svg>
</button>

A div that labels a group or area

If the div is a container you want named, give it a role that accepts a name, or use the right element:

<div role="group" aria-labelledby="ship-title">
  <h3 id="ship-title">Delivery options</h3>
  ...
</div>

<section aria-label="Customer stories">...</section>

Extra context for a span or text

Text elements cannot be named, so put the extra words in the text itself and hide them visually:

<span class="price">&pound;12<span class="visually-hidden"> per month</span></span>

.visually-hidden {
  position: absolute; width: 1px; height: 1px; overflow: hidden;
  clip-path: inset(50%); white-space: nowrap;
}

A button with visible text

Either drop the aria-label and let the text name the button, or make sure the label starts with the visible words. WCAG 2.5.3 Label in Name requires the accessible name to contain the visible text, so voice control users who say click Buy can still press it:

<!-- Fails 2.5.3 -->  <button aria-label="Add to basket">Buy</button>
<!-- Passes -->      <button aria-label="Buy Example Bakery sourdough loaf">Buy</button>

Screen reader differences on Windows

On Windows, three screen readers are common: NVDA, JAWS and the built-in Narrator. They read the same accessibility tree from the browser, but they choose differently what to say, which is why a label can seem to work on one and not another.

• Browse mode versus focus. When you Tab to a button or link, all three read its name. When you read the page with the arrow keys in browse mode, they read the content, and some skip names on elements that are not interactive or landmarks. An aria-label on a non-interactive container may only be read when you enter it, or not at all.
• Generic elements. Because naming a div or span is not allowed, screen readers are free to ignore it, and they do not behave the same way. Do not rely on a label that only one of them reads.
• Landmarks. A named <nav> or <section> is read when you move into it and shown in the landmarks list. Two navs named the same are confusing, so give each a distinct label, such as Main and Footer.
• Verbosity settings. Users can turn off some announcements. Test with default settings.

The fix for cross-reader differences is always the same: put the label on an element whose role supports it, and prefer visible text. If the name shows correctly in the DevTools Accessibility pane, the browser is doing its job, and a remaining difference is down to how a screen reader presents that role.

aria-label and translation by locale

An aria-label is a fixed string. It does not change by locale on its own: if your template says aria-label="Close", every visitor gets Close, whatever language the page is in. Automatic page translation tools may also skip or handle attribute text inconsistently, while they reliably translate visible text. So labels need to be translated by you, in the same way as the rest of your interface text.

• Use your translation system for the attribute. In Shopify themes: aria-label="{{ 'accessibility.close' | t }}". In WordPress: aria-label="<?php echo esc_attr__( 'Close menu', 'mytheme' ); ?>". In React apps, pass the string through the same i18n function you use for visible text.
• Prefer visible or visually hidden text. Text in the page, including visually hidden text, is translated with everything else, and aria-labelledby pointing at visible text follows the translation too.
• Set the page language. The lang attribute on the html element tells the screen reader which voice and pronunciation to use. A French page marked lang="en" is read with English pronunciation, which is a common reason labels sound wrong. See hreflang in Shopify for multi-language set-ups.

The fix, step by step

Edge cases worth knowing

• Icons inside named buttons. Hide decorative SVGs and icon fonts with aria-hidden="true", otherwise some screen readers read the icon too. See alt text for icons.
• The title attribute as a stand-in. A title shows a tooltip on mouse hover only, is not shown to keyboard or touch users, and is read inconsistently. It is not a replacement for a visible label. See the title attribute.
• Form fields. An aria-label on an input overrides its <label>. Keep the visible label and remove the aria-label, as covered in fixing form labels.
• Repeated labels. Ten buttons all labelled More are just as unclear as visible text More. Include the item, such as More about Example Bakery wedding cakes.
• Dynamic changes. Changing an aria-label while focus is on the element is not always announced. For a toggle, use aria-pressed or aria-expanded and keep the label stable.

Keeping your labels working

Add aria-labels in components, not page by page, so the right element and role are fixed once. Run the accessibility audit after theme or plugin updates, because a new version can change a button into a div. Keep the console snippet above in your test notes, and check any new icon-only control in the Accessibility pane before release. The wider rules for labels are in fixing ARIA labels, and invalid or misused attributes are covered in fixing ARIA errors.