The most common ARIA attributes, explained

ARIA is a way to enhance your code to provide more meaning, especially for assistive technology users. Over the years of auditing and consulting, we find these are the ARIA attributes that tend to be used (and misused) the most.

Only use ARIA when it’s necessary. If you don’t understand why you’re including an ARIA attribute, you probably shouldn’t do it! Using ARIA irresponsibly can confuse users more than help them.

Quick links:

• aria-label
• aria-labelledby
• aria-describedby
• aria-hidden
• ARIA roles

<aria-label>

What it is

This attribute gives a name (or label) to an element. Every meaningful element needs a name (WCAG 4.1.2). For example, a <button> usually takes its name from the visual text: <button>Submit</button> has the name of “Submit”. Likewise, an image’s name is its alt text and an input field takes its name from the <label> that’s associated with it.

<div> and <span> don’t need a name because they aren’t semantically meaningful.

When to use it

• Different to visible label or HTML label: Sometimes we want to give an element a name (or label) that is different from what is visible or that HTML has naturally assigned. For example, we might want a button to visually show “Submit” but for it to have more detail under the hood, so we use <aria-label> to give it a fuller name: <button aria-label="Submit personal details">Submit</button> means that a screen reader will read out the aria-label as this button’s name, instead of the visible label.

• Alternative labelling method: Other times, we need another method to give an element its name. The most conventional way to provide a label for an input field is the for/id method using the <label> and <input> elements. However, sometimes the <label> element isn’t used, like in a search field. One way to label the input field in this case is to use <aria-label>: <input aria-label="Search" type="text">

• Complex UI components: <aria-label> is also useful for more complex scenarios. A common design pattern for displaying news articles in a gallery is “tiles”: where there is an image, article title, some description, and perhaps a link or symbol to encourage the user to read more. All of these elements are then wrapped in an <a> link so that the whole “tile” is clickable. However, having all this information read out by a screen reader as the link’s name can be tiresome and confusing. Instead, applying <aria-label> to the wrapping <a> will mean the link takes on the label you ascribe to it. Remember though, it means any of the child information will not be read out.

<aria-label> trumps all other naming techniques. If you use the inherent HTML naming method plus <aria-labelledby> plus <aria-label>, only the text for <aria-label> will be acknowledged as the element’s name.

When not to use it

• Use HTML as your first option: HTML does a great job of providing elements with names/labels. Always use native HTML as your first choice when you can, like alt text on an image or the input/label combo to give elements their names.

• Redundant: It is not necessary to use <aria-label> when it is the same as the HTML name (for example, <button aria-label="submit">Submit</button>).

• The aria-label is more clear than the visible label: If you’re using <aria-label> to make an element’s programmatic label clearer like in the “Submit personal details” example above, consider making it the element’s visible label to benefit even more users.

• The aria-label doesn’t contain the visible label: Be careful of deviating the <aria-label> too far away from the visible label. People who use speech-to-text rely on the visible label to know how to call on elements, but if the <aria-label> doesn’t contain the visible text at all, they won’t be able to use that element. (WCAG 2.5.3 Label in Name)

<aria-labelledby>

What it is

Like <aria-label>, this attribute also changes the element’s name/label. Instead of stating the label outright like with <aria-label>, <aria-labelledby> points to another element, saying, “That text over there is the label for this element!” This is accomplished via id:

<img aria-labelledby="text">
<p id="text">This is the label</p>

When to use it

<aria-labelledby> is less common than <aria-label>. Some situations where aria-labelledby is appropriate include:

• Complex UI components: The “tile” example is a user interface that combines a number of elements together. Above, we used <aria-label> to label the tile. Alternatively, use <aria-labelledby> pointing to the article’s title. This reduces redundancy and human error because the title isn’t rewritten and is also useful for componentization.

• Custom form controls: When creating custom form controls that cannot use native HTML labels, such as custom dropdowns or sliders, aria-labelledby can associate the control with its label text.

• Dynamic content: If the content of an element changes based on user interactions or other factors, aria-labelledby can ensure that the updated label is conveyed to screen reader users.

When not to use it

Like <aria-label>, the preference is to always use HTML when possible. Avoid redundant use of ARIA, and make sure the visual label is sufficiently descriptive.

<aria-describedby>

What it is

Unlike <aria-label> or <aria-labelledby>, <aria-describedby> does NOT affect the element’s label. Instead, it provides a description to the element - it says so in the name!

<aria-describedby> provides a way to give more context or explanation to an element that may not be fully understood by all users, especially those using assistive technologies like screen readers. Like <aria-labelledby>, it points to another element that contains the additional description, and screen readers can announce this content when the associated element receives focus or is interacted with.

<button aria-describedby="disclaimer">Submit</button>
<p id="disclaimer">By clicking this button, you agree to our terms of use</p>

This code reads out as: “button, Submit, By clicking this button you agree to our terms of use”

When to use it

aria-describedby should be used when an element requires additional information to be conveyed to users, but adding the information directly to the element would make the content cluttered or less understandable for all users. Some common cases:

• Form inputs: “Help text” found beside or below an input field can be connected to the input field itself, so that a screen reader reads the input’s label then the help text.

• Complex UI components: When a user interface element has non-obvious functionalities or complex interactions, aria-describedby can provide instructions of its purpose or use.

• Error messages: When an error occurs in a form submission or application, you can use this attribute to associate the error message with the corresponding input field.

When not to use it

There are situations where using aria-describedby may not be appropriate:

• Redundant information: If the additional content only duplicates the information already present in the element or its label, using aria-describedby is unnecessary and can be confusing for users.

• Non-essential content: Avoid using aria-describedby for information that is not crucial for understanding the element's purpose or interaction. More information isn’t always better.

• Clear labels: Consider if the label of your elements is sufficiently descriptive. Improving these labels instead of providing descriptive instructions or text can help all users.

<aria-hidden>

What it is

<aria-hidden> is used to hide an element from accessibility tools, such as screen readers, while still allowing it to be visible to sighted users. This attribute accepts the values “true” or “false”.

When to use it

• Assistive technology user experience: Use aria-hidden="true" when the element is decorative, repetitive or when including the element would make the experience confusing for assistive technology users. For example, in our "tile" example, streamlining some of the content would reduce redundancy and improve user experience for assistive technology users.

• Programmatically hide an element: You can also use aria-hidden when toggling a display, like a hamburger menu. When the hamburger menu is visually closed, make sure it disappears for all users by applying aria-hidden. This will prevent assistive technology from announcing that the element is there.

When not to use it

<aria-hidden> is not a loophole to avoid making content accessible for assistive technology users. It is not appropriate to use this attribute to avoid coming up with alt text or considering different user experiences. Use ARIA to make content more accessible, not less.

ARIA Roles

What it is

Just like every element has a name, it also has a role - that’s the function that it plays. When you use standard HTML, the role is automatically assigned. The role is what you naturally think of when you see <button>, <input>, <a>, or <p>.

Roles are important because they inform assistive technologies about the type and purpose of each element, providing a more meaningful and accessible interaction for users. As an example, it’s meaningful to know if a block of text is a list or just a series of small paragraphs.

When to use it

• HTML isn’t enough: ARIA roles should be used when the standard HTML elements do not fully describe the purpose or behavior of an element. For example, while a standard dropdown menu exists in HTML as <select>, a combobox - where a user can type to filter options - doesn’t have a native HTML tag. The <role="combobox"> is useful here.

• Custom UI components: While hamburger menus appear on most websites these days, they are a custom component because they don’t naturally exist in HTML. The same can be said for some fancy or dynamic navigation menus or megamenus. We can enhance the meaning of these components using the menu role.

• Give meaning to container elements: <div> and <span> naturally don’t have any semantic meaning. If you want to give them meaning, you can apply a role to them. Just be careful - like any ARIA, by giving these elements roles you are committing to the full functionality of those roles! Think about any necessary child elements as well as keyboard functionality you need to include.

When not to use it

It’s not necessary to add a role onto elements that already have a role: <button> inherently has a role of button, and giving roles to landmarks like <main> and <navigation> is redundant. It’s almost always better to use the HTML tag if it's available instead of the role attribute.

Many roles like tablist or menu have obligatory and recommended parent-child relationships. Make sure to look those up and include them to make sure you understand them completely.

And finally, don’t use <a> with role=button. Just use <button>.

Conclusion

The themes that arise when we talk about ARIA attributes:

• Use HTML whenever possible

• ARIA attributes are more often used for custom or complex UI components.

• Make sure you understand how the ARIA attribute works - what it does, the values it takes, and any additional work you need to do around it like child elements or keyboard functionality.

Hopefully, by understanding the most commonly used ARIA attributes, developers can make good decisions about when and how they do - or don’t - use them.