Create accessible names for web objects

On this page:

Overview

Accessible names are used by assistive technology to identify the purpose of interactive elements and other objects in a web page, such as landmarks. Some examples of accessible names include the link text that identifies a link, the alt text used to describe an image, and the label on a checkbox. Without accessible names, these objects may only be identified as "link", "image", "checkbox", or by a generic landmark name by assistive technologies such as screen readers.

To understand the relationship between the accessible name, the accessibility tree, and the DOM, read Naming things to improve accessibility by Hidde de Vries.

Many objects require accessible names. These include all interactive elements, such as links, buttons, form controls, and modal windows, as well as images, headings, data tables and table headers, and some Accessible Rich Internet Applications (ARIA) landmarks.

Sources of the accessible name

The accessible name can come from the text content of the object or from another naming feature, such as an ARIA label, the alt attribute on an image, or the <label> for a form element.

If there is more than one possible source for an accessible name, the complex accessible name computation is used to decide which is the accessible name based on priority. A simplified version of the priority that will cover most cases is as follows:

  1. An aria-labelledby attribute
  2. An aria-label attribute
  3. A built-in naming feature for that object such as:
    • alt attribute for an image
    • <label> for a form control
    • <caption> for a table
  4. Content of the object, including CSS content
  5. A placeholder or aria-placeholder attribute for form controls
  6. A title attribute, when used as a tooltip
Note:
Do not rely on placeholder, aria-placeholder, or title attributes to provide the accessible name. In addition to other usability and accessibility concerns, some browsers and assistive technologies do not recognize them as part of the accessible name calculation.

To create good accessible names, it is essential to understand how the possible sources for the name interact. If an ARIA label (aria-label or aria-labelledby) is used, the ARIA label is the accessible name and will override the visible content, with aria-labelledby taking precedence over aria-label. For more about the order of priority for specific HTML elements, see HTML Accessibility API Mappings.

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 for aria-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

Design a form Landmarks and web page accessibility Label a form Use ARIA labels correctly for accessibility

This is document axuo in the Knowledge Base.
Last modified on 2023-10-04 10:59:12.