The HTML aria-label attribute
The aria-label attribute gives an element an accessible name from a string, as in <button aria-label="Close">. On a button or link, that string replaces the text inside as the name without appearing on screen. If the label text is already on the page, use aria-labelledby instead.
Overview
The aria-label attribute sets an element's accessible name, the short label assistive technology presents, from a string. A common case is a <button> that holds an SVG icon and no text. The attribute shows no tooltip and no text of its own.
The accessible name computation reaches the string before an element's <label>, alt text, own content or title. The one naming attribute ranked above it is aria-labelledby. On a <nav>, <section> or <table>, the string names the element and its content stays available.
WAI-ARIA 1.2 prohibits the attribute on the caption, code, deletion, emphasis, generic, insertion, paragraph, presentation (also called none), strong, subscript and superscript roles. The WAI-ARIA 1.3 Working Draft adds definition, mark, suggestion, term, time and tooltip.
The bans reach HTML elements through their roles, so authors must not use the attribute on a plain <div>, <span> or <p>, or on <code>, <strong> and <time>, among others. An explicit role that allows naming lifts the ban, as in <div role="group" aria-label="Filters">.
A prohibited aria-label has no dependable result. Chrome and Firefox still expose the text on a plain div, though the draft AccName 1.2 computation returns an empty string there. In practice, assistive technology supports it only on interactive elements, widgets, landmarks, images and iframes.
Syntax
<button aria-label="Close dialog">
<svg aria-hidden="true" width="16" height="16"></svg>
</button>
<nav aria-label="Footer links">...</nav>Values
| Value |
|---|
| A string (the accessible name). |
Example
<p>Click the speaker, then read the name it carries now.</p>
<button id="mute" type="button" aria-label="Mute" style="padding: 8px; line-height: 0;">
<svg aria-hidden="true" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
<path d="M4 9v6h4l5 4V5L8 9z"/>
<path id="waves" d="M16 9a4 4 0 0 1 0 6"/>
</svg>
</button>
<p role="status" id="out">aria-label is Mute. The button shows no text.</p>
<script>
const button = document.getElementById('mute');
const waves = document.getElementById('waves');
const out = document.getElementById('out');
button.addEventListener('click', function () {
const muted = button.getAttribute('aria-label') === 'Mute';
button.setAttribute('aria-label', muted ? 'Unmute' : 'Mute');
waves.setAttribute('stroke', muted ? 'none' : 'currentColor');
out.textContent = 'aria-label is ' + button.getAttribute('aria-label') + '. The button shows no text.';
});
</script>Best practices
- Write
aria-labelas a short name without the role word, so a button reads Close, not Close button. - Include a control's visible words in the string, ideally at its start, so the name contains the text people see.
- Try the native feature first. A
<label>on an<input>,alton an<img>ortitleon an<iframe>makes this attribute unnecessary. - Keep instructions out of the name, and put them in visible text tied in with aria-describedby, or in the draft aria-description attribute.
- Give each <nav> on a page its own string, such as Main and Footer, unless two hold identical content.
- Update the string when the action changes. Script can use
setAttributeor theariaLabelproperty, supported since Chrome 81, Edge 81, Firefox 119 and Safari 12.1.
