How to use aria-describedby the right way?

Profile picture of Arjan Schouten, author of the blog post.
Author Arjan Schouten

Last updated:

The ARIA standard is used by browsers, screen readers, and other assistive technology to make content accessible to everyone. One of the elements of the ARIA Standard is aria-describedby . How should you use it?

When to use aria-describedby?

aria-describedby should be used when an element needs a more extensive description. For example, an input field might need a more detailed explanation of the expected input. As a general rule of thumb: use aria-describedby only when the description contains complete or multiple sentences.

A real-world example for aria-describedby would be the BIC or SWIFT code for a bank account number. The input field for this might look like this:

<label for="swift-code">SWIFT code</label>
<input type="text" id="swift-code" aria-describedby="swift-explanation">
<p id="swift-explanation" aria-hidden="true">
    Your bank has a unique SWIFT code that usually consists of 11 characters. 
    An example SWIFT code is "BOFAUS3N" for the Bank of America. 
    You can find your bank's SWIFT code via: ...

Note that the text has aria-hidden="true" . Without the aria-hidden="true" , assistive technologies and screen readers might read the explanation twice. Once as the description of the input and once as regular text on the webpage.

How to use aria-describedby correctly?

To use aria-describedby correctly, wrap the descriptive text in an element such as <p> and give it a unique id. Add the aria-describedby="unique-id" attribute to the element that needs a description.

<input type="text" aria-describedby="unique-id">
<p id="unique-id">Your explanation goes here which is ideally a complete sentence.</p>

Make sure the id is unique on the web page and is exactly the same as the aria-describedby attribute value!

When to use aria-describedby vs aria-labelledby?

aria-labelledby and aria-describedby can be used on the same element.

  1. Use aria-labelledby for the name of an element. In general, this should only be a couple of words
  2. Use aria-describedby for a detailed explanation of the element. In general, this should contain complete sentences.

Check the correct usage of ARIA attributes on your website

Share this article

Was this article helpful?

Checkout the ExcellentWebCheck services

ExcellentWebCheck's goal is to improve the online user experience. The tools of ExcellentWebCheck help to detect and improve usability problems on your website.