aria-describedby

The global aria-describedby attribute identifies the element (or elements) that describes the element on which the attribute is set.

Description

The aria-describedby attribute is used to list the ids of the elements that describe the object, establishing a relationship between widgets or groups and the text that describes them.

The aria-describedby attribute can be used to associate static text with form elements, widgets, groups of elements, panes, regions that have a heading, definitions, and more. It can be used with semantic HTML elements and with elements that have an ARIA role.

The aria-describedby attribute is very similar to aria-labelledby attribute; while the aria-labelledby lists the ids of the labels or elements that describe the essence of an object, the aria-describedby lists the ids of the descriptions, or elements providing more information that the user might need. Both aria-labelledby and aria-describedby reference other elements to calculate a text alternative, but a label should be concise, where a description is intended to provide more verbose information.

The elements linked via aria-describedby don't need to be visible. It is possible to reference an element even if that element is hidden. For example, a form control can have a description that is hidden by default this is revealed on request using a disclosure widget like a "more information" icon. The sited user clicks on the icon; for assistive technology users the description is referenced from that form field directly with aria-describedby.

The aria-describedby property is appropriate when the associated content contains descriptions experienced as plain text. If the content contains a large amount of content, useful semantics, or has a complex structure requiring user navigation, use aria-details. aria-details allows assistive technology users to visit the associated structured content and provides additional navigation commands, making it easier to understand the structure, or to experience the information in smaller pieces.

Note: The aria-describedby content should only be a text string. If there are important underlying semantics in the content, consider using aria-details.

Example

<button aria-describedby="trash-desc">Move to trash</button>
...
<p id="trash-desc">Items in the trash will be permanently removed after 30 days.</p>

Note: The aria-describedby attributed is not designed to reference descriptions on an external resource—since it is an id, it must reference an element in the same DOM document.

Values

ID reference list

takes as its value the id or space separated list of ids of elements that describe the current element.

Associated roles

Used in ALL roles.

Specifications

Specification Status
Accessible Rich Internet Applications (WAI-ARIA) 1.1
The definition of 'ARIA: aria-describedby Attribute' in that specification.
Recommendation
WAI-ARIA Authoring Practices 1.2
The definition of 'describing with aria-describedby' in that specification.
Unknown

See Also