How to use aria-describedby the right way?
Last updated:
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: ...
</p>
...
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.
-
Use
aria-labelledbyfor the name of an element. In general, this should only be a couple of words -
Use
aria-describedbyfor a detailed explanation of the element. In general, this should contain complete sentences.
Check the correct usage of ARIA attributes on your website
We are sorry to hear that you are not satisfied with the content on this page.