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:

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?

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:

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.

Examples of typical sources of accessible names
  • 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:

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:

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:

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:

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 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:

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:

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:

If the element’s accessible name is different from its visible label, then:

For more on the importance of including an interactive element’s label in its accessible name, see:

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