The HTML aria-description attribute
The aria-description attribute holds an element's accessible description as a plain string, so no visible text is needed. It exists only in the WAI-ARIA 1.3 Working Draft of June 4, 2026, which says to use aria-describedby or aria-details for text the DOM already holds.
Overview
The aria-description attribute defines a string that describes or annotates the element it's on. The 1.2 Recommendation doesn't have it, and the 1.3 draft that defines it, dated June 4, 2026, may still be updated or replaced.
The draft gives it a narrow job. Authors may use it where "providing a visible description is not the desired user experience". A calendar day marked with dots is one such case, because no element holds the words 2 events.
Where the text lives decides the attribute. The draft says to use aria-describedby for a small description on the page, best read as a flat string, and aria-details for structured or long content that users can visit. Text found nowhere in the DOM is the case for this one.
The draft says browsers "MUST give precedence to aria-describedby over aria-description", and the draft description computation ranks both above title. Browsers handle an empty value differently. It ends Chrome's search and leaves Firefox free to use title.
Syntax
<button aria-label="Thursday 12" aria-description="2 events">12</button>Values
| Value |
|---|
| A string. |
Example
<p>Click a day to add an event. The dots are the only sign of it on screen.</p>
<div role="group" aria-label="Week of November 9">
<button type="button" aria-label="Monday 9">9 <span aria-hidden="true"></span></button>
<button type="button" aria-label="Tuesday 10">10 <span aria-hidden="true"></span></button>
<button type="button" aria-label="Wednesday 11">11 <span aria-hidden="true"></span></button>
<button type="button" aria-label="Thursday 12">12 <span aria-hidden="true"></span></button>
<button type="button" aria-label="Friday 13">13 <span aria-hidden="true"></span></button>
</div>
<p role="status" id="out">No day has an aria-description yet.</p>
<script>
const out = document.getElementById('out');
document.querySelectorAll('button').forEach(function (day) {
let events = 0;
day.addEventListener('click', function () {
events = (events + 1) % 3;
day.querySelector('span').textContent = '\u2022'.repeat(events);
if (events) day.setAttribute('aria-description', events + (events === 1 ? ' event' : ' events'));
else day.removeAttribute('aria-description');
const value = day.getAttribute('aria-description');
out.textContent = day.getAttribute('aria-label') + (value ? ': aria-description is ' + value : ': no aria-description');
});
});
</script>Best practices
- Remove
aria-descriptionwhen there's nothing to say, because browsers disagree about what an empty value means. - Don't repeat the accessible name in the string. Firefox leaves the description empty when the two match, while Chrome exposes both.
- Use
aria-describedbyon dialogs, because visible content makes important descriptive information less likely to be missed. - Add
aria-detailsalongside it when users need a summary and a place to go. An element may carry both.
