Main content

aria-describedby

Characteristics

Type:

  • String

Related Concepts:

  • Hint or Help in XForms
  • Label in XForms
  • Label in HTML
  • online help
  • HTML table cell headers
    • HTML label element and HTML table cell headers are de facto describedby values

Used in Roles:

  • All elements of the base markup (Global)
  • No role required

See related:

  • aria-labelledby

Value:

  • ID reference list

Identifies the element (or elements) that describes the object.

Aria-describedby is used when the content provided by the HTML tags is not sufficient to explain complete information to the user. For example, instructions for a form element, “Read more” as a link description is not sufficient to explain where the link targets to unless the user have some content surrounding. Sometimes the alternate text of the image is not sufficient to explain what the image has to say. In these situations aria-describedby will help in providing the additional information.

The aria-labelledby attribute is similar to aria-describedby in that both 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 aria-describedby property is intended to provide additional information which some users might need, and supplements the basic information provided by label.

The element or elements referenced by the aria-describedby comprise the entire description. Include ID references to multiple elements if necessary, or enclose a set of elements (e.g., paragraphs) with the element referenced by the ID. If more than one ID property is specified, all elements are combined together to create a single description.

Some scenarios where aria-describedby is beneficial

  • Instructions for form elements.
  • Additional description for links.
  • Additional information for images.

Using aria-describedby

Set a reference id to the element from which the content has to be extracted. 

<p id=”inst1”>The user name should be at least 8 characters.</p>

In the above example “inst1” is the id of the paragraph where the instruction is placed.

Using aria-describedby, call this content in the target element where you need the additional information with the reference id.

<label for=”uname”>User Name</label>
<input type=”text” id=”uname” aria-describedby=”inst1” />

In the above example, aria-describedby receives the information from the paragraph with the reference id and presents it to the user at the form element.

If the content needs to be extracted from different sources, use the procedure with a space between the ids.

The screen reader reads the instruction provided in the paragraph tag above along with the text field. This aria-describedby property can be used along with most of the html elements.

Note: Use the tab key for links and form elements to read out the information provided in the aria-describedby while navigating with NVDA or JAWS.

When aria-describedby is used along with images or any non-focusable elements use screen reader short-cuts such as “G” for images. Using JAWS the content in aria-describedby can be read by using the short-cut command JAWS (insert) key + alt + r to read the descriptive text (works best in Firefox). Safari on IOS also has good support for aria-describedby.

Note  For cross-browser compatibility, always use the aria attribute syntax to access and modify aria properties, for example object.setAttribute("aria-valuenow", newValue).

Syntax

HTML
<element aria-describedby="p" ... >
JavaScript
object.setAttribute("aria-describedby",value);var value = object.getAttribute("aria-describedby");

Microsoft Active Accessibility Properties:

  • N/A

UI Automation Properties: 

  • DescribedBy

UI Automation AriaProperties Property:

  • N/A
More in this category: « aria-controls aria-dropeffect »