SiteLint documentation and guidelines

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-describedby association 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-describedby deprives 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-describedby reference 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="" or aria-describedby without a value. The attribute exists but provides no reference, so no description is announced.
  • Typo or mismatch in ID reference – The aria-describedby value does not match any element’s id attribute 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-describedby reference, 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.

Correct example – valid ID reference
<p id="chart-desc">
  Bar chart showing quarterly revenue for 2025.
</p>
<iframe src="chart.html"
        aria-describedby="chart-desc"></iframe>
Incorrect example – missing referenced ID
<!-- 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.

Correct example – attribute omitted when no description is needed
<iframe src="decorative-video.html"
        title="Promotional video"></iframe>
Incorrect example – empty aria-describedby
<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.

Correct example – every referenced ID exists
<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>
Incorrect example – one ID is missing
<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.

Correct example – dynamic element inserted before the iframe
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);
Incorrect example – referenced element created after the 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.

Correct example – title attribute with aria-describedby
<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>
Incorrect example – generic title with no aria-describedby
<iframe src="analytics.html"
        title="Dashboard"></iframe>
<!-- Very generic title, no aria-describedby for context -->

Note that support for the title attribute varies across screen readers. For instance, VoiceOver by default has Hints set to Never or Speak after delay, which may prevent the title from being announced. Do not rely solely on title for critical information.

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-describedby attribute 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 id exists, but it does not verify that the element is visible, focusable, or contains meaningful text content.
  • Multiple aria-describedby on 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

Rule

  • Audit: accessibility
  • Standard: WCAG
  • Level: A
  • Success Criteria: 1.3.1
  • Rule ID: aria-describedby-association