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 an aria-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.

• the visible text contained in the element, such as the content in an <h1>, <a href> or <button> element
• an associated element, such as the <label> that provides the name for its related <input>, or the particular element(s) referenced by an aria-labelledby attribute on the element being named.
• a contained element, such as the <caption> element inside a <table>, or the <legend> element inside a <fieldset>
• an invisible attribute, such as the aria-label attribute, or an <img> element’s alt attribute.

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.

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.

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.

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.

1. Check that every element that needs an accessible name has one.
2. 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).