Description
The aria-describedby attribute is used to indicate the IDs of the elements that describe the object. It is used to establish a relationship between widgets or groups and text that described them. This is very similar to aria-labelledby: a label describes the essence of an object, while a description provides more information that the user might need.
The aria-describedby attribute is not used only for form elements; it is also used to associate static text with widgets, groups of elements, panes, regions that have a heading, definitions, and more. The Examples section below provides more information about how to use the attribute in these cases.
This attribute can be used with any typical HTML form element; it is not limited to elements that have an ARIA role assigned.
Value
a space-separated list of element IDs
Possible effects on user agents and assistive technology
Examples
Example 1: Application Landmark Descriptions
In the example below, an introductory paragraph describes a calendar application. aria-describedby is used to associate the paragraph with the application container.
<div role="applicaton" aria-labelledby="calendar" aria-describedby="info">
<h1 id="calendar">Calendar</h1>
<p id="info">
This calendar shows the game schedule for the Boston Red Sox.
</p>
<div role="grid">
...
</div>
</div>
Example 2: A Close Button
In the example below, a link that functions as a 'close' button on a dialog is described elsewhere in the document. The aria-describedby attribute is used to associate the description with the link.
<button aria-label="Close" aria-describedby="descriptionClose"
onclick="myDialog.close()">X</button>
...
<div id="descriptionClose">Closing this window will discard any information entered and
return you back to the main page</div>
Working Examples:
- Checkbox example uses
aria-describedby - Tooltip example uses
aria-describedby
Notes
- The
aria-describedbyattributed 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.
Used by ARIA roles
all elements of the base markup
Related ARIA techniques
Compatibility
TBD: Add support information for common UA and AT product combinations