What is aria-describedby? - Additional Descriptions for Accessibility
Information about the article
Author: Dmitry Dugarev
As a web developer, you want to ensure that your interfaces not only look good but are understandable to everyone. Sometimes an element—such as a complex form field or a button with unclear context—requires an additional explanation. This is where the WAI-ARIA attribute aria-describedby comes in. It is your tool to bridge a UI element and its more detailed description without overloading the visual design. It provides assistive technologies like screen readers with the necessary context that sighted users can often infer from the layout.
What is aria-describedby?
The official WAI-ARIA specification defines aria-describedby as follows:
Identifies the element (or elements) that describes the object. [1]
This means that aria-describedby establishes a programmatic connection between an element and one or more other elements that describe it.
Detailed Explanation
Imagine aria-describedby as a kind of extended tooltip for assistive technologies. While a label (<label> or aria-labelledby) indicates the name of an element (the "What"), the description (via aria-describedby) provides additional, contextual information (the "How" or "Why").
The value of the attribute is a space-separated list of id attributes. These ids must refer to elements that exist somewhere in the same document. The content of these referenced elements is then read by screen readers as the description for the original element.
A crucial difference from a label is how the information is presented. A label is usually read out directly along with the element's role (e.g., "Username, input field"). The description referenced by aria-describedby is often announced after a short pause or upon an explicit user action. This signals to the user that this is supplementary information, not essential information.
Text description for the diagram "Screen reader output process using aria-describedby."
The flow chart begins when a user focuses on an element. The system checks whether the element has an aria-describedby attribute.
- If yes, the screen reader first reads the role and name of the element. After a short pause, the content of the element referenced by
aria-describedbyis read. - If no, the screen reader only reads the role and name of the element.
In both cases, the process ends afterward.
What is it used for?
You use aria-describedby whenever an element requires additional explanations that go beyond its simple name. Typical use cases include:
- Form Instructions: You can use it to describe requirements for a password field (e.g., "Must be at least 8 characters long") or the format for a date input. Read more in our guide on accessible forms.
- Error Messages: If a form field has been filled out invalidly, you can link the error message to the
inputfield viaaria-describedby. This way, the user is informed directly upon focusing the field what went wrong. - Additional Information for Links and Buttons: A link with the text "Read more" is often not descriptive enough.
aria-describedbycan point to a neighboring sentence that provides context, e.g., "Read more about our new privacy policies." - Complex Widgets: For a slider,
aria-describedbycan be used to describe the current value or the function of the slider.
Practical Examples
- Good Example
- Bad Example
<div>
<label for="password">Password:</label>
<input type="password" id="password" aria-describedby="password-hint" />
<p id="password-hint">
Must contain at least 12 characters, one capital letter, and a number.
</p>
</div>
Explanation: Here, the input field is correctly connected via the aria-describedby attribute to the paragraph (<p>) containing the password requirements. A screen reader would output something like: "Password, input field. Must contain at least 12 characters, one capital letter, and a number."
<div>
<label for="password">Password:</label>
<input type="password" id="password" />
<!-- The connection is missing! -->
<p>Must contain at least 12 characters, one capital letter, and a number.</p>
</div>
Explanation: Although the description is visually present and near the field, the programmatic connection via aria-describedby is missing. A screen reader user tabbing through the form fields would likely miss this important information because it is not read out in the context of the input element.
Best Practices & Recommendations
Use Visible Descriptions
The content you reference with aria-describedby should generally also be visible to sighted users. Instructions or error messages are helpful to everyone. Hiding description texts (display: none; or visibility: hidden;) can lead to an inconsistent user experience and is ignored by some screen readers. This supports the WCAG success criterion that instructions must be available. [2]
Ensure Correct Naming
The accessible name of an element should always be defined first, preferably with a native <label for="...">. aria-describedby provides the description, not the name. A clear separation between the two is crucial for understandability. [3] [4]
Reference Only Relevant and Concise Content
Do not refer to a massive block of text. The description should be short and to the point. Long explanations can be very tedious for screen reader users, as they cannot easily skim them. Summarize the most important information concisely.
Be Cautious with aria-live
If the description text appears dynamically (e.g., an error message), you may need to use aria-live regions to immediately notify screen readers. However, combining aria-describedby and aria-live can be complex. A common technique is to place the error message in an aria-live container while simultaneously linking it to the input field via aria-describedby. [5]
Common Misunderstandings
aria-describedby is a substitute for <label>
This is false. aria-describedby supplements a label; it does not replace it. Every interactive element such as an input or button requires an accessible name. This is provided by <label>, aria-labelledby, or aria-label. The description is optional, supplementary information.
The content is always read immediately after the label
Not necessarily. Most screen readers introduce a short pause between the name and the description to signal to the user that this is supplementary information. Some configurations may also only read the description upon request. Therefore, do not rely on the description being perceived seamlessly as part of the label.
aria-describedby can reference a title attribute
No. aria-describedby always refers to the content of an element via its id. It cannot read the value of another attribute such as title or placeholder.
Related Terms
- aria-labelledby
- aria-label
- Accessible Name
- Screen reader
- Label
Frequently Asked Questions
What is the difference between aria-describedby and aria-labelledby?
aria-labelledby defines the name (Accessible Name) of an element by referring to one or more other elements. It replaces the element's own content for naming purposes. aria-describedby provides an description (Accessible Description) that supplements the name but does not replace it. In short: labelledby is for the "What," describedby is for the "More about it."
Can I make aria-describedby refer to multiple elements?
Yes, absolutely. The attribute value is a space-separated list of ids. The screen reader will read the contents of the referenced elements in the order they are listed in the attribute.
Example: aria-describedby="hint-1 hint-2".
Does aria-describedby also work with hidden elements?
Technically yes, but it is not good practice. If you refer to an element that is hidden with display: none or visibility: hidden, it will still be read by most screen readers. The problem is that you create a discrepancy between what sighted users perceive and what screen reader users hear. If the information is important, it should be accessible to everyone.
Should I use aria-describedby for error messages?
Yes, this is one of the best use cases! When a user makes an error, link the error message to the faulty input field via aria-describedby. Additionally, set aria-invalid="true" on the field. This way, the user is immediately informed about the error and its description upon refocusing the field.
Note
The information contained in this article, particularly regarding laws and guidelines such as the WCAG, is intended for informational purposes only and does not constitute legal advice. For specific legal questions concerning digital accessibility, you should always consult a qualified lawyer.
About the author