The HTML aria-details attribute
Through aria-details, an element points at fuller content, such as a chart's data table, by id. Assistive technology can then tell users the detail exists and take them to it. Unlike a description, the referenced content isn't flattened to a string, so its structure survives.
Overview
The aria-details attribute connects an element to a separate element with more detailed information about it. Its presence lets assistive technologies make users aware of that information and navigate to it. The attribute is global, and it supplies no accessible name.
The referenced content stays intact. It's left out of the accessible description computation, so a table isn't flattened to a string and keeps its rows. The element gets a relation to the target, and aria-details adds nothing to its description.
The value depends on the version. WAI-ARIA 1.2 allows one id, while the 1.3 Working Draft of June 4, 2026 allows a list, so a paragraph can reference several unrelated comments.
The target should stay in the accessibility tree, visible to all users. Chrome and Firefox drop the relation when the target uses hidden, display: none, visibility: hidden or aria-hidden, or sits inside a closed <details>, but keep it for an off-screen target or a closed <details> itself.
The 1.3 draft lets the target's role say what kind of detail it is. A comment role means a comment, and a term pointing at a definition role means a definition. A figure's caption, a doc-footnote and a doc-endnote work the same way, and any other role is a general annotation.
Syntax
<img src="sales.png" alt="Sales by quarter" aria-details="sales-data">
<details id="sales-data">
<summary>Sales table</summary>
<p>Q1 was $120k and Q2 was $240k.</p>
</details>Values
| Value |
|---|
| One element id, or a list of ids in the WAI-ARIA 1.3 draft. |
Example
<p style="margin: 0 0 6px">Open the table. The chart points at it either way.</p>
<svg role="img" aria-label="Sales by quarter" aria-details="sales-data" width="96" height="40" viewBox="0 0 96 40">
<rect x="0" y="20" width="40" height="20" fill="#1e72e0"/>
<rect x="52" y="0" width="40" height="40" fill="#1e72e0"/>
</svg>
<details id="sales-data">
<summary>Sales by quarter</summary>
<table>
<tr><th>Quarter</th><th>Sales</th></tr>
<tr><td>Q1</td><td>$120k</td></tr>
<tr><td>Q2</td><td>$240k</td></tr>
</table>
</details>
<p role="status" id="out" style="margin: 6px 0 0">aria-details points at sales-data, which is closed.</p>
<script>
const target = document.getElementById('sales-data');
target.addEventListener('toggle', function () {
const id = document.querySelector('svg').getAttribute('aria-details');
document.getElementById('out').textContent = 'aria-details points at ' + id + ', which is ' + (target.open ? 'open.' : 'closed.');
});
</script>Best practices
- Give the element a short name as well, such as an image's
alttext, becausearia-detailsdoesn't supply one. - Reference a <details> element itself, not something inside it.
- Point at one wrapper when several comments apply. The 1.3 draft allows that, and says a container of comments should have the group or region role.
- Use one id if you must conform to the 1.2 Recommendation, whose value type is a single ID reference, not a list.
