Skip Navigation

Don't Overwrite Visual Labels With `aria-label`

Published

Last updated


The aria-label property can be extremely useful when used correctly. When used incorrectly, it can wreak havoc on speech-input user experiences. It’s an easy mistake to make and luckily it’s pretty easy to fix!

For the TL;DR: jump to How do I fix mismatched aria-labels and visual labels?

A note about Voice Control

As of my understanding in July 2024, Apple’s Voice Control requires its users to say an element’s entire Accessible Name to interact with it. So while SC 2.5.3: Label in Name only states the Accessible Name must contain the label, it’s best to make the visible label and Accessible Name match exactly.

Thank you Tori Clark for tweeting this info to me back in April of 2023. Sorry it took so long to add here!

Nothing missed! The only thing that might be worth delineating more is that Voice Control demands the -full- accessible labels be spoken, whereas partial labels work great with Dragon and Windows Speech Recognition as long as it's early in the accessible name/label.

What is the aria-label property?

As defined by the WAI-ARIA 1.2 standards, the aria-label property “defines a string value that labels the current element”. It has the same purpose as the aria-labelledby property, which references another element that labels the current element. The purpose of both of these properties is to provide an Accessible Name of the current element.

Related to these properties is the aria-describedby property, which references another element that describes the current element. The purpose of this property is to provide an Accessible Description for the current element. The Accessible Name should be concise, and the Accessible Description should be more verbose and complement the Accessible Name.

The Accessible Name is part of what screen readers use to announce elements to a user when they come into focus. A <button> with no aria-label and plain text between its opening and closing tags would have an Accessible Name that matches its plain text. That same <button> can have its Accessible Name overridden with something completely different using the aria-label property.

Use the next two example code snippets to compare how the same button sounds with and without an aria-label.

Example 1: <button> with no aria-label

The code:

<button>OK</button>

The output:


Example 2: <button> with an aria-label

The code:

<button aria-label="Confirm selection">OK</button>

The output:


Why does aria-label need to match the visible label?

First of all, an aria-label must match its element’s visible label because there is a Level A WCAG Success Criterion that says so. SC 2.5.3: Label in Name says:

For user interface components with labels that include text or images of text, the name contains the text that is presented visually.

This means that the Accessible Name computed for an element should contain the text of the element’s visual label. One best practice for this is to have the Accessible Name start with the visual label’s text. So if a link contains the text “Learn more” and the author of that link wants to include more information about the link’s purpose in the aria-label, a good practice is to start the aria-label with “Learn more”.

If you’re like me and my ADHD brain, you might need a little more reasoning than “the rules say so” to motivate you to follow the rules. A lot of people don’t like being told what to do, and that’s fine!

So why do we need to follow Success Criterion 2.5.3? It partially has to do with speech recognition technology. As it turns out, the Accessible Name for elements is how speech-input users can interact with elements in a web page.

Referencing our two previous examples:

For speech-input users who rely on visual labels to come up with voice commands, there is no way for them to know before speaking a command if the Accessible Name of an element differs from its visual label. They will have to speak a command and find out if it does or does not work. If a command doesn’t work, they may retry a couple of times. If the command does not work at all because the Accessible Name doesn’t match the visual label, their energy has been wasted and they’re also stuck.

What happens when aria-label doesn’t match the visible label?

As I wrote this article, I started to learn about Voice Control on Mac. I wanted to see if I could find a real-world example of speech-input navigation being broken due to mismatched visual labels and accessible names. I found a couple of examples right on the Twitter home page.

Unfortunately, more than half of the main navigation links have accessible names that don’t match their visual labels. Even in the cases where a link’s aria-label began with the text in the visual label, I was not successful in activating those links with speech input. I made countless attempts.

Here’s a quick demo of me trying to activate the “Messages” link that shows on the home page of Twitter:

Are there other users that benefit from aria-label matching the visible label?

This article primarily focuses on the sighted speech-input user’s experience, but there are other users affected by this issue as well. Think of a sighted screen reader user that comes across the <button> element in Example 2. It is presented by their screen reader as “Confirm selection, button”, but the text in the button says “OK”.

This can be a very confusing and stressful experience for the user. How can they be certain the issue is with the website and not their own action? We’re imposing an extra cognitive load on the user to process the mismatched audio and visual experiences. There is also extra cognitive load required to first memorize the behavior, and then recall it the next time they come across the element.

It’s not necessary or kind to do this to users. It’s energy-draining, and energy is an extremely limited resource for all kinds of people who rely on accessible interfaces.

How do I fix mismatched aria-labels and visual labels?

Now that you know mismatching aria-label and visual labels is harmful to speech-input users, how do you go about preventing that harm? First, I’d recommend reading Playing with state by Sarah Higley and Be Careful with Dynamic Accessible Names by Adrian Roselli.

Second, think about whether or not you need to provide an aria-label for the element that differs from its visual label. Some cases that come to mind:

After you’ve spent time thinking thoroughly about your aria-labels and visual labels, make the updates and test them with your users. It’s hard for us to know if something is usable if it doesn’t intersect with our own needs. The only experiences we can truly be experts in are our own. Don’t miss the step where you get your information from the source of truth: your users with expertise in their lived experiences.

Article Updates

  1. : First published.
  2. : Added Related Resources section with one link (Designing and coding for voice).
  3. :
Back to Top