How aria-label affects the accessible name
Browsers compute the accessible name in a fixed order. aria-labelledby takes precedence over aria-label. aria-label in turn wins over names from native HTML: a form field’s <label>, an image’s alt, an iframe’s title and the text inside a button or link.
In practice, a button that reads “Save” but carries aria-label="Submit" is announced as “Submit”. Someone who sees “Save” and controls the page by voice may not be able to activate it.
When to use aria-label
- Icon-only buttons and links, such as close, search, menu or cart.
- Several landmarks of the same type on one page, such as main navigation and footer navigation.
- A dialog or region whose title is not on screen. If the title is visible, reference it with aria-labelledby instead.
- A form field with no visible label when the design really cannot show one. A visible <label> is better for everyone.
When not to use aria-label
- When native HTML does the job. The first rule of ARIA: if a native element or attribute already has the semantics and behavior you need, use it instead of ARIA.
- On generic elements such as a div or span with no role. WAI-ARIA 1.2 prohibits naming roles including generic, paragraph, code, strong and emphasis, and assistive technologies may ignore such a name.
- When the name does not contain the visible text. WCAG 2.5.3 Label in Name (Level A) requires the accessible name to contain the text shown on the component, ideally at the start.
- For longer hints and instructions. A description that supplements the name belongs in aria-describedby.
aria-label vs aria-labelledby vs aria-describedby
MDN recommends aria-labelledby over aria-label when a visible label exists that you can reference. Do not set both on one element, because aria-label will be ignored.
| Attribute | What it does | When to use it |
|---|---|---|
| aria-label | Names the element from text written in the attribute. The text is not visible. | There is no visible text to point to. |
| aria-labelledby | Names the element from the content of another element (by id). Takes precedence over aria-label. | A heading or text on screen already names the element well. |
| aria-describedby | Adds a description, such as password rules. Does not replace the name. | Instructions, hints and helper messages. |
Examples
The first example shows correct use: an icon-only button and two navigation landmarks. The second shows two common mistakes and their fixes.
<button type="button" aria-label="Close">
<svg aria-hidden="true">…</svg>
</button>
<nav aria-label="Main">…</nav>
<nav aria-label="Footer">…</nav><!-- Mistake: the name does not contain the visible text (WCAG 2.5.3) -->
<button aria-label="Submit form">Save</button>
<!-- Fix: remove aria-label, or start it with the visible text -->
<button>Save</button>
<!-- Mistake: a name on a generic element -->
<div aria-label="Price">$49</div>
<!-- Fix: show the label as text -->
<p>Price: $49</p>How to check aria-label
Open the accessibility pane in your browser’s developer tools and check the element’s computed name and where it comes from. Automated tests catch a missing name or aria-label on a prohibited role, but they cannot tell whether the name is understandable. Check that with a screen reader such as NVDA or VoiceOver.
aria-label is an attribute from the W3C WAI-ARIA standard that gives an element an accessible name announced by screen readers. The text is not visible on the page, so it is mainly used where a visible label is missing, such as an icon-only button.
aria-label supplies the name directly as text in the attribute. aria-labelledby points by id to another element whose content becomes the name, and it wins when both are set. If a heading or label is visible on screen, prefer aria-labelledby.
It should not be used on a generic element with no role. WAI-ARIA 1.2 prohibits naming the generic role, and assistive technologies may ignore it. Show the text on screen, or use an element with a suitable role such as button, nav or a section with a heading.
It should not. On an image aria-label takes precedence over alt, but alt is the standard HTML way to describe an image and works without ARIA. For a decorative icon inside a button, add aria-hidden="true" to the icon and name the button.