Use aria-describedby to provide additional descriptions and context for elements that need it.
Description
The aria-describedby attribute provides an accessible description for an element by referencing the id of another element on the page. This rule checks that when an <iframe> element carries an aria-describedby attribute, the value is not empty and every ID it references corresponds to an existing element in the DOM. If a referenced ID is missing or the attribute is blank, assistive technologies receive no description, leaving users without critical context about the embedded content.
For example, an iframe that embeds a chart or a map should describe what it contains so that screen reader users can decide whether to interact with it. A valid aria-describedby points to a nearby <p> or <div> that holds that description. This rule enforces that the association is physically present in the DOM. See Understanding SC 1.3.1 – Info and Relationships for more details.
Disabilities impacted
- Visual disabilities – Blind users who rely on screen readers depend on the
aria-describedbyassociation to hear a description of the iframe’s content. Without a valid reference, they cannot determine whether the embedded resource is relevant, leading to confusion and wasted time navigating irrelevant content. - Cognitive disabilities – Users with memory or comprehension impairments benefit from concise, additional descriptions that clarify the purpose of an iframe. A broken or empty
aria-describedbydeprives them of this contextual support, making it harder to understand the page layout. - Screen reader and low-vision users – Even with magnification or screen reader assistance, users need accurate descriptions to identify embedded content such as videos, maps, or data visualisations. When the
aria-describedbyreference points to a nonexistent element, the description is silently dropped with no error feedback.
Why it matters
Associating a description with an element via aria-describedby is a core WAI-ARIA pattern that bridges the gap between visual layout and non-visual access. When the association breaks – either because the attribute is empty or the target ID does not exist – screen readers silently skip the description. Users are left unaware that additional context exists, which can make interactive widgets, charts, and embedded media unusable. Ensuring that every aria-describedby reference resolves to a real element is a basic prerequisite for any accessible interface and helps satisfy WCAG Success Criterion 1.3.1.
Coding problems and solutions
Common coding problems
- Empty attribute value – Setting
aria-describedby=""oraria-describedbywithout a value. The attribute exists but provides no reference, so no description is announced. - Typo or mismatch in ID reference – The
aria-describedbyvalue does not match any element’sidattribute due to a spelling error, case mismatch, or trailing whitespace. - Referencing a dynamically removed element – The description element is added by JavaScript but later removed or replaced without updating the
aria-describedbyreference, leaving a dangling pointer. - Whitespace-only value – The attribute contains only spaces or tabs, which after trimming results in an empty string and triggers the empty-value check.
- Multiple ID references where some or all IDs are missing – Using space-separated IDs (e.g.,
aria-describedby="desc1 desc2") where one or more of the referenced elements do not exist in the DOM.
How to fix it
Always provide a non-empty aria-describedby with valid ID references
The primary fix is to ensure that the aria-describedby attribute contains at least one ID that matches an element present in the same document. Verify that the referenced element exists at the time the iframe is rendered.
<p id="chart-desc">
Bar chart showing quarterly revenue for 2025.
</p>
<iframe src="chart.html"
aria-describedby="chart-desc"></iframe><!-- No element with id="chart-desc" exists -->
<iframe src="chart.html"
aria-describedby="chart-desc"></iframe>Avoid empty or whitespace-only aria-describedby
An aria-describedby attribute that is empty, contains only whitespace, or has no value assigned will be treated as missing and provide no description to assistive technology. Remove the attribute entirely if no description is needed, or supply a valid ID.
<iframe src="decorative-video.html"
title="Promotional video"></iframe><iframe src="chart.html"
aria-describedby=""></iframe>Validate all IDs in a space-separated list
When using multiple ID references (e.g., aria-describedby="a b"), each individual token must correspond to an existing element. This rule checks every ID in the list, and a single broken reference will still generate a report.
<p id="summary">Sales summary for Q1 – Q4.</p>
<p id="note">Figures are in thousands.</p>
<iframe src="dashboard.html"
aria-describedby="summary note"></iframe><p id="summary">Sales summary.</p>
<!-- Missing id="note" -->
<iframe src="dashboard.html"
aria-describedby="summary note"></iframe>Ensure dynamically added descriptions are stable in the DOM
When content is loaded or updated asynchronously, the element referenced by aria-describedby must already be present before or at the same time as the iframe. If you remove or replace the description element, update the aria-describedby reference accordingly.
const desc = document.createElement('p');
desc.id = 'live-chart-desc';
desc.textContent = 'Live stock prices updated every 5 seconds.';
document.getElementById('chart-container')
.insertAdjacentElement('afterbegin', desc);
const iframe = document.createElement('iframe');
iframe.src = 'live-stocks.html';
iframe.setAttribute('aria-describedby', 'live-chart-desc');
document.getElementById('chart-container')
.appendChild(iframe);const iframe = document.createElement('iframe');
iframe.src = 'live-stocks.html';
iframe.setAttribute('aria-describedby', 'live-chart-desc');
// Description element does not exist yet
document.getElementById('chart-container')
.appendChild(iframe);
// Created too late – the rule already ran
const desc = document.createElement('p');
desc.id = 'live-chart-desc';
desc.textContent = 'Live stock prices.';
document.getElementById('chart-container')
.appendChild(desc);Use title as a fallback when aria-describedby is not appropriate
When an iframe cannot have a visible description element nearby, the title attribute can serve as an accessible name. However, title has inconsistent screen reader support and should not be the sole mechanism for critical descriptions.
<iframe src="analytics.html"
title="Quarterly analytics dashboard"
aria-describedby="analytics-desc"></iframe>
<p id="analytics-desc">
Interactive charts with revenue, costs, and profit margins.
</p><iframe src="analytics.html"
title="Dashboard"></iframe>
<!-- Very generic title, no aria-describedby for context -->Known Limitations
- Single-page applications (SPAs) – SPAs that dynamically render iframes after initial page load may not be captured if the DOM selector runs before the framework mounts. An additional audit pass after the SPA has settled may be needed.
- Shadow DOM encapsulation – Iframes and their description elements inside closed shadow roots are invisible to
document.getElementById. The rule cannot resolve ID references that cross shadow boundaries. - Cross-origin iframes – The rule checks only the
aria-describedbyattribute on the iframe element itself. Content inside a cross-origin iframe cannot be inspected, so descriptions that refer to elements inside the iframe’s own document are not validated. - Dynamic DOM mutations – If the description element is added or removed after the audit runs, the report may be stale. This rule captures a snapshot of the DOM at audit time and does not watch for live mutations.
- Hidden or off-screen description elements – The rule confirms that an element with the matching
idexists, but it does not verify that the element is visible, focusable, or contains meaningful text content. - Multiple
aria-describedbyon the same page – The rule validates each iframe independently but does not cross-check duplicate or conflicting ID references across different iframes on the same page.
Resources
- Understanding WCAG SC 1.3.1 – Info and Relationships
- WCAG 2.2 Success Criterion 1.3.1
- MDN – aria-describedby
- W3C ARIA in HTML
- WAI-ARIA Authoring Practices
Rule
- Audit: accessibility
- Standard: WCAG
- Level: A
- Success Criteria: 1.3.1
- Rule ID:
aria-describedby-association