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