Accessible names
An accessible name identifies a user interface (UI) element to assistive technologies and their users — this is especially important for interactive components.
Meeting the Web Accessibility Standard
When an element’s accessible name can be programmatically determined and means the same thing as its visible label, this meets WCAG 2:
- Success Criterion 1.3.1 Info and Relationships (Level A)
- Success Criterion 4.1.2 Name, Role, Value (Level A).
When an element’s accessible name includes the text or text equivalent of the element’s visible label, this meets WCAG 2 Success Criterion 2.5.3 Label in Name (Level A).
When an interactive element made from non-text content, like an image, has a descriptive accessible name, this meets WCAG 2 Success Criterion 1.1.1 Non-text Content (Level A).
On this page
- What’s an accessible name?
- How accessible names are derived
- When to provide an accessible name
- How to provide accessible names
- Accessible name must include any visible label
- Testing for accessible names
What’s an accessible name?
An accessible name is a short descriptive name that assistive technologies (AT) use to identify a user interface (UI) element to the user. An accessible name is programmatically determinable — it can be read by a machine.
An accessible name might be:
- visible to sighted users, such as the visible text label in a
<button>
element - visually hidden in the HTML markup, such as the
alt
attribute on an<img>
element or anaria-label
attribute on a<ul>
element.
The accessible name is a property of accessible objects in the accessibility tree that makes web content available to AT, which in turn present that content to users.
For more on how web pages are made accessible to AT users, see the Knowledge Area: Browsers, code and assistive technologies.
How accessible names are derived
UI elements can get their accessible names from different sources, and what those sources are depends on the element.
These different sources of accessible names follow certain rules and have an order of precedence.
For detailed information on the rules and order of precedence that browsers follow to compute the accessible name of different HTML elements, see:
- How do you name an element? — What’s in a name? — Sarah Higley
- What is an accessible name? — TPGi
- Naming Techniques — ARIA Authoring Practices Guide — W3C
- Accessible name calculation — ARIA Authoring Practices Guide — W3C
- Accessible Name and Description computation — HTML Accessibility API Mappings — W3C.
When to provide an accessible name
Some elements, especially interactive elements like <a href>
, <button>
and <input type="text">
, must have an accessible name to be usable with assistive technologies.
Some elements must not have an accessible name. For example, <div>
and <span>
elements have a generic
role that prohibits them from having name provided by the page author. See Elements that cannot be named using aria-label
or aria-labelledby
below.
Other elements can make content easier for people to use if an accessible name is provided. For example, giving the <ul>
and <nav>
elements an accessible name enables assistive technologies to provide useful context to users.
To learn about when and how to properly give an element an accessible name, see:
- What needs a name? — What’s in a name? — Sarah Higley
- Which elements need explicitly set names? — Practical accessibility, part 2: Name (almost) everything — Filament Group
How to provide accessible names
A good accessible name is logical and concise. For guidance on creating reliable accessible names that really help users, see:
- Better accessible names — Hidde de Vries
- My Priority of Methods for Labeling a Control — Adrian Roselli
- Cardinal Rules of Naming — ARIA Authoring Practices Guide — W3C
- Composing Effective and User-friendly Accessible Names — ARIA Authoring Practices Guide — W3C.
Using aria-label
and aria-labelledby
In some scenarios, you can use the aria-label
or aria-labelledby
attributes to provide an accessible name.
If a UI element can have an accessible name, and it has either of these attributes, the attribute’s value takes precedence and is used for the accessible name over any other source for an accessible name. For more details, see ARIA Labels Always Win — WebAIM.
Note: Accessible Rich Internet Applications (WAI-ARIA), or just ARIA, is a W3C technology for programmatically adding semantic information about content — such as its name, role, state or other properties. ARIA is intended to be used when the host markup language — for example, HTML — does not include elements or attributes with the semantics needed to represent the content.
When ARIA is used correctly, it enables assistive technologies (AT), especially screen readers, to relay the necessary semantic information about the content to the user.
As a rule, do not use ARIA if a native HTML element or attribute with the needed semantics or features already exists.
For more information, see:
If an element has both an aria-label
and an aria-labelledby
attribute, the aria-labelledby
takes precedence over aria-label
.
To learn more about these attributes, see The difference between aria-label and aria-labelledby — Léonie Watson.
aria-label
The aria-label
attribute is useful for giving an element an accessible name when there is no content in the element or elsewhere on the page that can be used to provide its name.
The aria-label
attribute takes a string of text (a sequence of letters, numbers and punctuation characters without any HTML markup) as its value, and that text becomes the element’s accessible name.
For details on creating an accessible name using using aria-label
, see:
- aria-label — MDN Web Docs
- Using aria-label — Labeling Regions — WAI Tutorials — W3C
- ARIA6: Using aria-label to provide labels for objects — WCAG 2 — W3C
- ARIA8: Using aria-label for link purpose — WCAG 2 — W3C
- ARIA14: Using aria-label to provide an invisible label where a visible label cannot be used — WCAG 2 — W3C
- aria-label property — Accessible Rich Internet Applications (WAI-ARIA) — W3C.
Be careful with aria-label
The aria-label
attribute can cause problems if used incorrectly. Be aware of the following conditions that apply to aria-label
.
aria-label
is invisible to sighted users
The aria-label
attribute is not visible to sighted users.
If a sighted user cannot easily determine an element’s accessible name from its visible label, for instance, if that label is an unfamiliar icon, then an aria-label
attribute will not help them because they cannot see it.
This is especially a problem for sighted speech recognition users who need to know an element’s accessible name to be able to interact with it. This is one reason that it’s important to provide text labels alongside interactive icons. For more, see How icons are ruining interfaces — Axess Lab.
Since aria-label
is not visible to users, it’s sometimes used to give an element a special accessible name for screen reader users only. However, the aria-label
overrides the element’s other sources for an accessible name, such as the element’s visible content. If the element’s visible label does not match the accessible name that’s derived from the aria-label
attribute, this can be problematic for some users. For example, a sighted screen reader user will both see the visible text label and hear the non-matching accessible name, potentially confusing them.
To avoid creating this issue, see Accessible name must include any visible label.
aria-label
is not reliably translated by translation services
Some users rely on browsers’ built-in automatic translation services, or those provided by Google or Bing. However, not all such translation services translate content in an aria-label
attribute.
For details, including a few techniques other than aria-label
, see aria-label Does Not Translate — Adrian Roselli.
aria-labelledby
The aria-labelledby
attribute is useful when there is content elsewhere on the page that can be used as an element’s accessible name. The aria-labelledby
attribute takes the id
attribute value of one or more elements that already exist on the page and, together, form the accessible name.
For details on using aria-labelledby
, see:
- aria-labelledby — MDN Web Docs
- ARIA7: Using aria-labelledby for link purpose — WCAG 2 — W3C
- ARIA9: Using aria-labelledby to concatenate a label from several text nodes — WCAG 2 — W3C
- ARIA10: Using aria-labelledby to provide a text alternative for non-text content — WCAG 2 — W3C
- Using aria-labelledby — Labeling Regions — WAI Tutorials — W3C
- ARIA13: Using aria-labelledby to name regions and landmarks — WCAG 2 — W3C
- ARIA16: Using aria-labelledby to provide a name for user interface controls — WCAG 2 — W3C
- aria-labelledby usage notes — HTML5 Accessibility
- aria-labelledby property — Accessible Rich Internet Applications (WAI-ARIA) — W3C.
aria-labelledby
works with hidden content
Just like aria-describedby
, aria-labelledby
can reference and create an accessible name from elements that are hidden from users, whether that’s through CSS display:none
or visibility:hidden
, or with aria-hidden="true"
.
For examples of this feature of aria-labelledby
, see:
- Short note on aria-labelledby and aria-describedby — TPGi
- Hiding Content Has No Effect on Accessible Name or Description Calculation — Using ARIA — W3C.
aria-labelledby
flattens content structure
It’s important to remember that any content referenced by an aria-labelledby
attribute is flattened. This means that any HTML structure in the content is removed, and the content is converted to a simple text string (a sequence of letters, numbers and punctuation characters without any HTML markup).
Therefore, make sure that any content referenced by aria-labelledby
is simple text with no structure.
Elements that cannot be named using aria-label
or aria-labelledby
Some elements are not permitted to have an accessible name provided by the author. In such cases, if page authors use aria-label
or aria-labelledby
, these attributes will not be reliably exposed to assistive technologies.
For more on which elements cannot take an aria-label
or aria-labelledby
attribute, see:
- Requirements for use of ARIA attributes to name elements — ARIA in HTML — W3C
- Roles which cannot be named (Name prohibited) — WAI-ARIA — W3C.
Using the title
attribute
If an element’s accessible name cannot be derived from its typical sources, including aria-label
and aria-labelledby
, the title
attribute can — but usually should not — be used as the source for the accessible name.
Note: Where possible, avoid using the title
attribute because it is problematic for several reasons, and generally should not be used except with <abbr>
and <iframe>
elements.
For reasons to avoid using the title
attribute, see:
Accessible name must include any visible label
In some cases, an element’s accessible name is the same as its visible label. In others, an element’s accessible name comes from some visually hidden attribute, such as aria-label
.
Note: In web accessibility, the word “label” sometimes refers to the <label>
element, and sometimes to an element’s visible label or identifier that is visually presented to the user — for example, some text or a graphic.
To read about the difference between an element’s accessible name and its label, see:
Voice recognition and screen reader software both use an element’s accessible name to identify it. Many voice recognition and screen reader users can also see, in which case they might also use the element’s visible label to identify it.
For this reason, the accessible name should match the label of a UI element, or at least, whatever is in the label needs to be in the accessible name, ideally at the beginning of the accessible name. This is to ensure that:
- how a sighted user identifies the element (by its visible label) is consistent with how that element is identified by screen reader software (by its accessible name).
- what a speech recognition user needs to say to activate the element (its accessible name) is the same as or contains everything that’s in the element’s visible label.
If the element’s accessible name is different from its visible label, then:
- a sighted user and a blind user might get confused when the sighted person refers to the element by its label and the blind person refers to it by its accessible name
- a speech recognition user will not be able to activate the element whose label is one thing but whose accessible name is something else entirely.
For more on the importance of including an interactive element’s label in its accessible name, see:
- Label in Name — Success Criterion 2.5.3 (Level A) — Pearson
- Understanding Success Criterion 2.5.3: Label in Name — WCAG 2 — W3C
Testing for accessible names
Use your web browser’s developer tools to inspect the accessibility information for the page you are viewing. For instructions, see Inspecting the accessibility tree — Knowledge Area: Browsers, code and assistive technologies.
- Check that every element that needs an accessible name has one.
- For each element that has an accessible name, check that:
- the accessible name correctly identifies the element
- if the element’s visible label is nothing but a graphic, the accessible name means the same thing as the graphic
- if the element’s visible label has any text, the accessible name includes that text (preferably at the beginning of the name).