Accessible descriptions

An accessible description provides additional information about a user interface (UI) element to help assistive technology users understand it and its context.

Meeting the Web Accessibility Standard

When a visible description associated with an element or widget is programmatically exposed as the element or widget’s accessible description, this meets WCAG 2 Success Criterion 1.3.1 Info and Relationships (Level A).

On this page

• What’s an accessible description?
• How accessible descriptions are derived
• When to provide an accessible description
• How to provide accessible descriptions
• Testing for accessible descriptions

What’s an accessible description?

An accessible description provides assistive technology (AT) users, mainly screen reader users, with more information about a user interface (UI) element than is provided in its accessible name.

The accessible description 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 descriptions are derived

There are only a few sources for accessible names: the aria-describedby, aria-description and title attributes.

These sources of accessible descriptions 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 description of different HTML elements, see:

• Describing Techniques — ARIA Authoring Practices Guide — W3C
• Accessible description calculation — ARIA Authoring Practices Guide — W3C
• Accessible Name and Description Computation — HTML Accessibility API Mappings — W3C.

When to provide an accessible description

The accessible description is an optional property of UI elements represented in the accessibility tree. However, in the following and similar situations, explicitly providing an accessible description is necessary.

• Some UI controls, like links and buttons, are accompanied by additional text that explains what will happen when they are activated. In the visual UI, the additional text is positioned next to the control so that sighted users understand that it serves as a description for the control.
• Form controls often have instructions, hints or other information regarding the input that’s expected from the user. This information comes before or after the form control in a way that makes it clear to sighted users which control it’s related to.
• An <img> element always needs an alt attribute, but is sometimes also accompanied by a longer passage of text in the page that describes the image for those who cannot see it or who need help understanding it.

In all these cases, the description needs to be programmatically associated with the related element to ensure that it’s available to AT users, especially screen reader users.

In other scenarios, wherever there is additional information about an element or a more complex widget or web application that could help AT users understand it or its context, turn that information into an accessible description. Usually, that extra information will be helpful to all users, but even if it is not visible on the page, it can still be provided to AT users. For more, see Using aria-describedby and aria-description below.

To learn more about when to provide an accessible description, see:

• Describing Techniques — ARIA Authoring Practices Guide — W3C
• Using aria-describedby to provide helpful form hints — TPGi.

How to provide accessible descriptions

Using aria-describedby and aria-description

For almost all UI elements that can have an accessible description, the ARIA attribute, aria-describedby, is currently the primary way to associate a description with that element.

Soon, there will also be the aria-description attribute that can be used to provide an accessible description.

If an element has both an aria-describedby and an aria-desciption attribute, aria-describedby takes precedence over aria-description.

Elements that work with aria-describedby and aria-description

Compared with aria-label and aria-labelledby, which do not work on every element, both aria-describedby and aria-description are meant to work on all elements.

However, not all browsers and screen readers currently support the use of aria-describedby and aria-description on all elements. So, it’s important to test the use of those attributes to make sure that they are correctly exposed to screen readers.

aria-describedby

The aria-describedby 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-describedby, see:

• aria-describedby — MDN Web Docs
• Describing aria-describedby — TPGi
• Using aria-describedby to provide helpful form hints — TPGi
• ARIA1: Using the aria-describedby property to provide a descriptive label for user interface controls — WCAG 2 — W3C
• ARIA15: Using aria-describedby to provide descriptions of images — WCAG 2 — W3C
• aria-describedby property — Accessible Rich Internet Applications (WAI-ARIA) — W3C.

aria-describedby works with hidden content

Just like aria-labelledby, aria-describedby can reference and create an accessible description 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 using this feature of aria-describedby, 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-describedby flattens content structure

It’s important to remember that any content referenced by an aria-describedby attribute is flattened. That means that any HTML structure in the referenced 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-describedby is simple text with no structure.

If the content being referenced by aria-describedby is structured, and that structure is important, you may want to use the aria-details attribute. For more, see aria-details — MDN Web Docs.

aria-description

The aria-description attribute takes a string of text (a sequence of letters, numbers and punctuation characters without any HTML markup), and that text becomes the element’s description. However, aria-description is new in WAI-ARIA 1.3, and not currently supported across all common browsers. But when it is, it will be useful for giving an element an accessible description when there is no content in the element or elsewhere on the page that can be used to provide the description

For details on using aria-description once it has full browser and screen reader support, see:

• aria-description — MDN Web Docs
• aria-description: By Public Demand and to Thunderous Applause — HTML5 Accessibility
• aria-description property — Accessible Rich Internet Applications (WAI-ARIA) — W3C.

Be careful with aria-description

The aria-description attribute can cause problems if used incorrectly. Be aware of the following conditions that apply to aria-description.

aria-description is invisible to sighted users

The aria-description attribute is not visible to sighted users. If a sighted user cannot easily determine an element’s accessible description from visible content on the page, then an aria-description attribute will not help because they cannot see it in the first place.

Since aria-description is not visible to users, it’s sometimes used to give an element a special accessible description for screen reader users only. Consider if the accessible description provided in the aria-description attribute might be useful to any sighted users. If it is, make the description visible on the page and instead use aria-describedby to reference it.

aria-description 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 will translate content in an aria-description attribute.

Using the title attribute

In the absence of an aria-describedby or aria-description attribute, an element’s title attribute, if it has one, will be used as the source for the accessible description, but only if the title was not already used for the element’s accessible name.

Testing for accessible descriptions

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. For each element that’s accompanied by one or more passages of plain text that describe the element or its context, check that the element has one of the following:
   • an aria-describedby attribute that references the id attribute value of each of the related passages of text
   • an aria-description attribute (once it’s supported), that includes the same information that’s in the related passages of text
   • a title attribute that includes the same information that’s in the related passages of text.
2. For each element that’s not accompanied by one or more passages of plain text describing the element, but that has an accessible description through its aria-description (once it’s supported) or title attributes, check that the attribute’s value is a reasonable description of the element or its context.