Auroratide

Coding + Storytelling

How to NOT use aria-label

Accessibility

Topics
  • accessibility
  • html
  • aria-label
  • wai-aria
  • naming

The aria-label attribute gives a textual name to an HTML element. A close button is a classic example:

<button aria-label="Close">×</button>

Visually, you would see a "×", which indicates a window will be closed. Meanwhile, someone who uses a screen reader will hear "Close, button", which conveys the same thing. Without the aria-label, they would hear "Times, button" instead, which is rather confusing.

So, aria-label is very useful! However, generally speaking, it isn't the first tool you should reach for when providing a textual representation for an element.

So, let's explore when not to use aria-label!

Don't use aria-label for roles where it isn't allowed!

You can't put aria-label on a span:

<!-- Don't do this! -->
<span aria-label="Apple">Orange</span>

It might look like visual readers get an orange, while screen readers get an apple, but that's not really what happens here. In fact, what happens is not well-defined nor consistent across browsers and assistive tools.

The span is just one example. The aria-label definition lists many roles for which it is forbidden.

The general rule is that aria-label can only be used on name-assignable roles, which includes interactive elements and not static elements.

Instead, you have a couple of choices:

  • Explicitly assign an interactive role
  • Make the screen reader text visually hidden with CSS
<!-- Assign a role, but also just use a normal button...? -->
<span role="button" aria-label="close">×</span>

<!-- Make the text visually hidden -->
<span class="visually-hidden">Apples</span>
<span aria-hidden="true">Oranges</span>
Avoid aria-label where regular HTML can be used instead!

HTML is already designed to provide textual representation for virtually anything. As such, you will almost always rely on these mechanisms rather than needing aria-label.

  • The text content of a button is its textual representation (<button>Submit</button>).
  • Images are supplied an alt attribute which is its textual label.
  • Form controls have a corresponding label element to describe them.
  • Figures and tables have figcaption and caption respectively.
  • Even page sections are generally described by their page headings (<h2>, <h3>, etc).

Notably, most of these mechanisms (by default) provide the same text to sighted and non-sighted people alike. So, aria-label is best reserved for when these shouldn't be the same, or for when the sighted representation conveys meaning without text (such as using the "×" symbol to represent "close").

<!-- Avoid this... -->
<table aria-label="Quarterly Earnings">

<!-- ...when you can use native HTML -->
<table><caption>Quarterly Earnings</caption></table>
Avoid aria-label for text that is valuable to everyone!

Most textual representations provided by HTML are both visible and available for screen readers simultaneously. And that's for good reason:

For example, perhaps there are keyboard shortcuts you want people using screen readers to be aware of (e.g. "Press Esc to exit the modal"). Yet, that text is just as useful to sighted people using a mouse, as they may prefer the alacrity of pressing Esc over moving a mouse to a button.

To hide info like this by default, consider using tooltips or the details HTML element.

I wrote about this because I had developed a tendency to overuse aria-label anytime I needed something "for screen readers", and doing so led to web pages that were either non-compliant (failing axe accessibility testing) or less accessible than I thought they were.

As usual, the first rule of using ARIA is to not use ARIA:

  • Don't use aria-label for roles where it isn't allowed!
  • Avoid aria-label where regular HTML can be used instead!
  • Avoid aria-label for text that is valuable to everyone!