ARIA labels
On this page:
Overview
Accessible Rich Internet Applications (ARIA) labels can be used when native labels aren't possible or don't provide enough context. For example, ARIA labels can be used to name landmarks and connect error messages to form fields. Before using ARIA labels, it's important to understand the different attributes and how to use them properly.
ARIA labeling attributes
There are three related ARIA attributes for labeling:
- Use
aria-label
to directly apply a label to the current element. - Use
aria-labelledby
to label an element using the text of one or more elements. - Use
aria-describedby
to provide a description using the text of one or more elements but not label the element.
aria-label
Use aria-label
when there is no visible label.
<button aria-label="close">X</button>
<nav aria-label="main">
aria-labelledby
Use aria-labelledby
to point to a new label located in another element. It should reference the unique id
of the element containing the label.
<aside aria-labelledby="facts">
<h2 id="facts">Some really neat facts</h2>
In this example, the <aside>
, a complementary landmark, has the label, or accessible name, Some really neat facts
.
aria-describedby
Use aria-describedby
to add a description that can be announced by assistive technology. As with aria-labelledby
, it should reference the unique id
of the element containing the description.
<label for="name">Name (required)</label>
<input type="text" id="name" aria-describedby="error">
<span id="error">Name is required. Please enter your response.</span>
Multiple id references
More than one id
can be referenced by aria-labelledby
or aria-describedby
, including the id
on the element itself.
<span class="visually-hidden" id="context">plus context</span>
<a href="#" id="self" aria-labelledby="self context">Link text</a>
In this example, the accessible name of the link is Link text plus context
, while the visible link text is Link text
.
These concepts can be used for any element that can be labeled using ARIA labels, including tables and table cells, landmarks, and form fields.
When to use ARIA labels
ARIA labels are best supported for landmarks and interactive elements like widgets and form controls. Their support on links is inconsistent, depending on the combination of browser and assistive technology. So when should you use an ARIA label?
In terms of ARIA labels, there are two types of objects:
- Alerts, dialogs, landmarks, and similar items are named only with ARIA labels.
- Buttons, form controls, links, tables, images, and other items have built-in naming through content (for example, link text) or another naming feature (for example, a form
<label>
).
For the first type of object, the answer is simple: Use ARIA labels.
For the second type, the first rule of ARIA provides guidance: if you can name the object using a built-in method, you should.
But sometimes the built-in name is insufficient, and ARIA labels can provide needed context for assistive technologies. Before adding an ARIA label, consider these questions:
- Should the built-in name be improved instead? If an ARIA label would help people using assistive technology understand the object, would that same information help people not using assistive technology?
- Instead of changing the name, is a description necessary to provide more information, such as needed formatting on a form field?
- Will the name need to be translated into other languages? Browser support for translating
aria-label
is currently limited to Chrome when using the Google Translate API. (Translation should not be an issue foraria-labelledby
because it refers to text content.)
If you use an ARIA label, understanding the difference between aria-label and aria-labelledby will help you choose the best option.
As a best practice, the accessible name should match or start with the visible content. This helps people using assistive technologies like voice control to identify the object.
Related documents
This is document axgb in the Knowledge Base.
Last modified on 2023-07-17 14:54:03.