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?

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.

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:

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:

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.

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:

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.

Note: In version 1.3 of WAI-ARIA, which is still being drafted, there is a new aria-description attribute. Once it has full support across common browsers and screen readers, this attribute will work just like the aria-label attribute in that it takes a string of text, but in this case, that text is used to create the element’s accessible description. For more, see aria-description property — WAI-ARIA 1.3 — W3C.

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

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:

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.

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:

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.