Skip to content

aria-label

The aria-label should be used to provide a text alternative to an element that has no visible text on the screen.

Definition

aria-label is an attribute defined in the WAI-ARIA(opens in a new tab) specification. This specification extends native HTML, allowing you to change the way an HTML element is "translated" into the accessibility tree.

By default, an HTML element will use its text content as the accessibility label. If an element has aria-label, the accessible name becomes the string that it's passed in the attribute.

<button>send</button>
// accessible name: send
<button aria-label="send email">send</button>
// accessible name: send email

You can make use of aria-label by adding it to certain Footnote 1) HTML elements.

<button
aria-label="menu"
class="burger"></button>

VoiceOver on OSX will read this button as "menu, button", as shown in the image below.

Screenshot of VoiceOver on OSX  when focusing the button in the example

You should use it when you have non-textual indication of an element's purpose, but still need to provide text alternates for users who use assistive technology, such as screen readers.

Example 1: Icon Button

<button aria-label="Close">
<svg
focusable="false"
aria-hidden="true"
viewBox="0 0 24 24"
>
<path
d="M19 6.41L17.59 5 12 10.59 6.41 5 5
6.41 10.59 12 5 17.59 6.41 19 12
13.41 17.59 19 19 17.59 13.41 12z" />
</svg>
</button>
<input
type="text"
name="name"
placeholder="What's your name?"
aria-label="Your name" />
<nav aria-label=’primary’>
<ul>
...List on links here...
</ul>
</nav>
<nav aria-label=’secondary’>
<ul>
...List on links here...
</ul>
</nav>
See "Multiple Navigation Landmarks" pattern
<section aria-label="projects">
...
</section>
<section aria-label="team">
...
</section>

When label text is visible on screen, you should use aria-labelledby instead of aria-label.

// ⛔ BAD: using aria-label when text
// is visible on screen
<nav aria-label="Related Content">
<h2>Related Content</h2>
<ul>
...List on links here...
</ul>
</nav>
// ✅ Good: using aria-labelledby when text
// is visible on screen
<nav aria-labelledby="nav-title">
<h2 id='nav-title'>Related Content</h2>
<ul>
...List on links here...
</ul>
</nav>

The title attribute shows as a tooltip when the mouse goes over the element. While it can be useful for people using the mouse, it will not be available to keyboard-only users. Note that while title attribute is listed in the text-alternative computation algorithm, it might not be supported in some combinations of screen-reader/browsers (at the time of writting, IE 11 and NVDA).

In short, If you find yourself using the title attribute to provide additional information, it's probably better to either use aria-label or think of an alternative (e.g.: disclosure additional information to users such as a tooltip).

React, in particular JSX, supports all aria-* attributes. Contrary to other HTML attributes, ARIA attributes in jsx should be hyphen-cased as they are in plain HTML.

{/* Static string */}
<button aria-label="Send">...</button>
{/* Dynamic string */}
<button aria-label={labelVariable}>...</button>

In Angular, aria-* attributes are treated like any other HTML attributes and can either be binded to static attributes or to dynamic variables (using the attr prefix).

// Static string
<button aria-label="Send">...</button>
// Dynamic string
<button [attr.aria-label]="labelVariable">...</button>

In Vue, aria-* attributes are also treated like any other HTML attributes and can either be binded to static attributes or to dynamic variables (using the :aria-label prefix).

<!-- Static string -->
<button aria-label="Send">...</button>
<!-- Dynamic string -->
<button :aria-label="labelVariable">...</button>

If the element has text content, you DON'T need to add aria-label, as it is redundant.

// ⛔ BAD: over-using aria-label
<button aria-label="Send">Send</button>
// ✅ GOOD: use it only when needed it
<button>Send</button>