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.

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.

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.

<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.”

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.

• aria-label overrides an element’s name with contents you specify.
• aria-labelledby replaces an element’s name with contents from another node on the page. You’d use this when you’d already have a visible label anyways.
• aria-describedby sets your element’s description to the contents of another node on the page. This is great for noncritical, supplemental information.
• aria-description… is coming.

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.