aria-label, aria-labelledby, and aria-describedby: What's the Difference?

Introduction #

ARIA is a set of HTML attributes designed to tweak how a webpage is exposed to assistive technology. It can be‚Ķ a lot. There are presently 36 aria-* attributes, each with their own specific or general use cases, their own rules for compatible elements and roles, and their own browser/‚Äčscreenreader support tables. On top of that, they can be hard to keep straight‚ÄĒwhen should you use aria‚ÄĎvaluenow versus aria‚ÄĎvaluetext, or aria‚ÄĎchecked versus aria‚ÄĎselected?

I've written about ARIA before, but this time, I'd like to hone in on three ARIA attributes that, in my experience, are just similar enough to be confusing: aria‚ÄĎlabel, aria‚ÄĎlabelledby, and aria‚ÄĎdescribedby.

Have you used these attributes before?

If you've used these attributes before, pause here and ask yourself: What's the difference between aria‚ÄĎlabel, aria‚ÄĎlabelledby, and aria‚ÄĎdescribedby? When might you use one over the other? Can they be used together?

Names and Descriptions #

Behind the scenes, your browser packages up an alternative version of the DOM, called the accessibility tree, to expose to assistive technologies. This tree is made up of objects‚ÄĒbundles of properties that describe your elements' functionality. Two of these properties are the accessible name and the accessible description.

The accessible name is a required field. It's the key way that elements are exposed and announced by assistive technologies. One handy way to think about the name is that it's probably how you'd describe the element to someone else using the page: "Select the Username field," or "Click the Edit button." Semantic HTML elements generally have their own default way of calculating their name. For instance, images use their alt text, buttons and links use their text contents, form fields use associated <label> elements, and so forth.

Names are critical for interacting with elements through assistive technology. Voice control users may say the name of a control, such as a button, aloud to interact with it. Additionally, some screenreader navigation modes, such as VoiceOver's Rotor, allow users to skim through the page using only elements' roles and names.

On the other hand, the accessible description is optional, and it represents supplemental information about the given element. Screenreaders and other assistive technologies may opt to skip over descriptions in some navigation modes such as continuous reading, where the description may cause needless clutter.

Let's revisit those initial questions.

Now that we've talked about names and descriptions, what do you think the difference between aria‚ÄĎlabel, aria‚ÄĎlabelledby, and aria‚ÄĎdescribedby is? Has your answer changed?

ARIA gives web developers the tools to curate how elements on our page are exposed to assistive technology by modifying properties such as these! Let's look at how we can use aria‚ÄĎlabel, aria‚ÄĎlabelledby, and aria‚ÄĎdescribedby to curate useful names and descriptions.

aria-label #

aria‚ÄĎlabel overrides an element's name, replacing it with text that you specify. For instance, consider the following button:

<button aria-label="Close">
√ó
</button>

By default, the button's name would have been "√ó." However, √ó is meant to be a multiplication symbol, and screenreaders will announce it as such. That means that, while this might be a visually appealing close button, it won't be super useful or descriptive for disabled users who rely on assistive technology. To remedy this, we put aria-label="Close" on the button. The button's name is now "Close," which is much more descriptive and intuitive.

It can be tempting to use aria‚ÄĎlabel all over the place to tailor announcements and pronunciations for screenreader users, but, as with all ARIA, it's important to be judicious. For one thing, while aria‚ÄĎlabel is well-supported for interactive elements, it's not well-supported for static text elements. For another, such label overrides often rely on faulty assumptions about how users navigate your page. Finally, if you find yourself reaching for aria‚ÄĎlabel often, that may be a sign that you should reconsider your semantic markup or retooling your design to include more visual labels that everyone can access.

aria-labelledby #

aria‚ÄĎlabelledby also overrides an element's name, replacing it with the contents of another element. aria‚ÄĎlabelledby is set to the id of another element whose contents make up a useful name. You can think of it as kind of like a generalized version of the <label> element's for attribute. This is useful when you already have another element that serves as a visual label for something. By linking the two elements with aria‚ÄĎlabelledby like this, we ensure that we only have to update content in one place and our accessible name updates automatically. Something, something, Don't Repeat Yourself.

One handy use case for aria‚ÄĎlabelledby is labelling sections. When sections are labelled, screenreader users can skim through them like a table of contents, using them to skip to sections of the page they care about. Usually, these sections already have a heading element that can serve as a nice, convenient label!

<section aria-labelledby="intro-heading">
<h2 id="intro-heading">
Introduction
</h2>
<p> … </p>
</section>

aria‚ÄĎlabelledby shares many of the same caveats as aria‚ÄĎlabel such as compatible elements and user expectations. Additionally, aria‚ÄĎlabelledby will supercede aria‚ÄĎlabel if both attributes are provided.

aria-describedby #

aria‚ÄĎdescribedby sets an element's description to the contents of another element. Like aria‚ÄĎlabelledby, aria‚ÄĎdescribedby takes an id. Descriptions are helpful for providing longer-form, supplemental information about an interface control that should probably be exposed along with the rest of the element, but which wouldn't make sense as part of the element's name.

We could, for instance, use aria‚ÄĎdescribedby to link an input with an element that provides further details about the input's expected format:

<form>
<label for="username">Username</label>
<input id="username" type="text" aria-describedby="format" />
<p id="format">
Username may contain alphanumeric characters.
</p>
</form>

The above input will have the name "Username" (given to it by its <label>) and the description "Username may contain alphanumeric characters." That means that while assistive technologies will call the input field "Username," when the user actually navigates to the field, they'll be informed of both its name and the expected format. Nifty.

Because descriptions are supplemental, they may not be exposed to the user in every navigation mode. This is a great thing, because it reduces clutter! For instance, many screenreader users will skim through a whole form to find out which fields are available before filling it out, but they wouldn't need your descriptions until they start filling out each field. However, this does mean you should go in with the assumption that your provided description might not be guaranteed.

Providing Multiple IDs #

Should you need, both aria‚ÄĎlabelledby and aria‚ÄĎdescribedby support passing multiple IDs. When assembling the element's name or description from multiple elements, the browser will concatenate each element's contents into one big string.

Expanding on our username field example from earlier…

<form>
<label for="username">Username</label>
<input id="username" type="text" aria-describedby="length format" />
<p id="length">
Username must be 6 to 15 characters.
</p>
<p id="format">
Username may contain alphanumeric characters.
</p>
</form>

Our input's full description now reads "Username must be 6 to 15 characters. Username may contain alphanumeric characters."

Hidden Labels and Descriptions #

aria-labelledby and aria-describedby interact with a few other attributes‚ÄĒnamely, hidden or aria‚ÄĎhidden‚ÄĒin an interesting way. In an ideal, 100% compatible world, when you set hidden or aria‚ÄĎhidden="true" on an element, that element won't be exposed to assistive technology so, for instance, screenreaders won't announce it. But what happens if you use a hidden element's id in another element's aria‚ÄĎlabelledby or aria‚ÄĎdescribedby?

What happens is kind of cool‚ÄĒthe hidden element stays hidden, but its contents populate the other element's name or description anyways! You might not use this with aria‚ÄĎlabelledby because using aria‚ÄĎlabel is probably easier in these cases. Where this comes in handy, though, is with descriptions.

Currently, there isn't an aria‚ÄĎdescription attribute yet, though this attribute is on its way. Until it arrives and is widely supported by browsers and assistive technology alike, however, the only way to set an element's description is to introduce another DOM node to the page. By default, this means that you have a new node that assistive technology could expose independently of the labelled/described element. In other words, you could be introducing potentially confusing clutter. We could place an aria‚ÄĎhidden on our description to minimize that misleading clutter.

But enough talk‚ÄĒhere's an example!

<table>
<thead>
<tr>
<th role="columnheader" scope="col" aria-sort="none">
<button aria-describedby="sort-description">
<svg><!-- some sort icon --></svg>
Name
</button>
</th>
<th> … </th>
</tr>
</thead>
<tbody>
…
</tbody>
</table>

<p id="sort-description" hidden>
Sort this table alphabetically by name.
</p>

In this example, we have a table whose column headers have buttons that will sort the table. That sorting behavior is made evident for sighted users with some recognizable sort icon, but blind users wouldn't get any cues to the buttons' functionality. To compensate, we give the button a description using aria‚ÄĎdescribedby, pointing to a <p> tag outside of the table. We wouldn't want users to navigate to the <p> on its own, however, so we apply hidden to it. Now our sort button has a description of "Sort this table alphabetically by name." without any of the ensuing clutter! ūüôĆūüŹĽ

TL;DR #

aria‚ÄĎlabel, aria‚ÄĎlabelledby, and aria‚ÄĎdescribedby can all be used to bring extra clarity to a given element when it's exposed to assistive technology.

As always, be sure to test your ARIA in a variety of browsers and assistive technologies to be confident that your ARIA is adding clarity rather than taking it away.

Interested in learning more?

If you're ever in doubt about if and how to use ARIA, the best place to check is the W3C's ARIA Authoring Practices, which describe guidelines and patterns for effective ARIA use. It even has a whole section devoted to names and descriptions!