The aria-details attribute is used when an element on a page has additional detailed information available elsewhere.
It creates a connection between that element and the detailed information.
Let's take the following simple bar chart:
It could have some descriptive alt text such as:
<img
src="sales-chart.png"
alt="Sales increased steadily throughout the year"
>However, we may also want to provide a more detailed explanation of the chart somewhere on the page, ideally near the image.
aria-details can point from the chart to that detailed explanation.
<img
src="sales-chart.png"
alt="Sales increased steadily throughout the year"
aria-details="sales-details"
>
<div id="sales-details">
<h2>Detailed sales information</h2>
<p>
Sales began at $20,000 in January, increased to $24,000
in February, and reached $31,000 in March.
</p>
</div>
The matching sales-details values tell assistive technologies:
There is more detailed information about this item available on the page.
What does a screen reader announce?
When a screen reader user reaches the image, the screen reader does not normally read all of the detailed information.
Instead, it will generally announce something along the lines of:
"Sales increased steadily throughout the year, image, has details."
The exact words and order will vary depending on the screen reader, browser and user settings. The important thing is that the user hears:
- the image's short alternative text
- that it is an image
- that additional details are available
And then it stops. The detailed content is not automatically read as part of the element. The user can choose to move to or explore it using the features provided by their screen reader.
This is one of the key reasons aria-details exists: it can point to a large amount of information without forcing the screen reader to announce all of that information every time the user encounters the original item.
More importantly, this additional information can be structured as needed, using headings, paragraphs, lists, links or tables.
What can aria-details be used on?
aria-details is not just for images. It can be used whenever content has additional details associated with it, such as:
- a chart that has a detailed explanation
- a paragraph that has one or more reviewer comments
- a form field that has extensive instructions
- a table that has detailed notes or assumptions
- a button whose action has complex consequences
- a section of a document that has additional annotations
For example, a form field could point to a separate block of detailed instructions:
<label for="password">Password</label>
<input
type="password"
id="password"
aria-details="password-requirements"
>
<div id="password-requirements">
<h2>Password requirements</h2>
<ul>
<li>At least 12 characters</li>
<li>At least one number</li>
<li>At least one symbol</li>
</ul>
</div>In ARIA 1.3, aria-details can reference multiple pieces of content by using space-separated IDs. For example, a paragraph in a document editor could point to two separate comments:
<p aria-details="comment-1 comment-2">
All customer records will be retained for seven years.
</p>
<div id="comment-1">
<p>Should this retention period be reviewed?</p>
</div>
<div id="comment-2">
<p>Legal has confirmed that seven years is required.</p>
</div>How is this different from aria-describedby?
aria-describedby is useful when the extra information can be presented as part of the item's description, and the user doesn't normally have to go anywhere else to hear it.
This makes it suitable for relatively short, straightforward descriptive information.
"Here is some extra text to read with this element."
aria-details works differently: the referenced information is not added to the announcement. Instead, the user is told that additional information exist and can decide whether to explore it.
"There is more detailed content available if you want to explore it."
Here's our earlier chart image marked up using aria-describedby:
<!-- aria-describedby -->
<img
src="sales-chart.png"
alt="Sales increased steadily throughout the year"
aria-describedby="sales-details"
>
<div id="sales-details">
<h2>Detailed sales information</h2>
<p>
Sales began at $20,000 in January, increased to $24,000
in February, and reached $31,000 in March.
</p>
</div>
The image would be announced as something like:
"Sales increased steadily throughout the year, image. Detailed sales information. Sales began at $20,000 in January, increased to $24,000 in February, and reached $31,000 in March."
As you can see, the detailed information becomes the image's description, read out in full every time. It's also flattened into a single string of text. Users can't skip between parts of it or jump to just the piece they want, the way they can with normal semantic content. It's all or nothing.
Here's the same chart image marked up using aria-details:
<!-- aria-details -->
<img
src="sales-chart.png"
alt="Sales increased steadily throughout the year"
aria-details="sales-details"
>
<div id="sales-details">
<h2>Detailed sales information</h2>
<p>
Sales began at $20,000 in January, increased to $24,000
in February, and reached $31,000 in March.
</p>
</div>The image would be announced as something like:
"Sales increased steadily throughout the year, image, has details."
In this case, users hear that more information is available and can choose whether to explore it. When they navigate to the additional content, they can move through it as normal page content.
When should you use each one?
Use aria-describedby when the additional information makes sense to hear as part of the item's description — short, straightforward, useful to hear immediately.
<button aria-describedby="delete-help">
Delete account
</button>
<p id="delete-help">
This action cannot be undone.
</p>The button would be announced as something like:
"Delete account, button. This action cannot be undone."
Use aria-details when the additional information is something the user may want to explore separately — long, complex, structured, or made up of several distinct pieces.
<button aria-details="delete-details">
Delete account
</button>
<div id="delete-details">
<h2>What happens when you delete your account?</h2>
<p>Your profile and saved preferences will be deleted.</p>
<p>Your records will be retained for seven years.</p>
<p>
<a href="/data-retention">Read our data policy</a>
</p>
</div>In this case, the button would be announced as something like:
"Delete account, button, has details."
The first example is a short warning that makes sense to hear with the button. The second is substantial information that's better explored separately.
Takeaway
Use aria-details when an element has additional information that is too detailed or structured to be useful as a simple description.