JavaScript Element ariaDescribedByElements Property

Beginner
5 min read
Updated: Nov 2026
3 examples
Property

Definition

In JavaScript, the ariaDescribedByElements property of Element is an array of elements that provide an accessible description for this element — longer help text than a label (MDN).

Read the notes below before you get or set this property. Prefer feature detection when support is limited.

Syntax

Use el.ariaDescribedByElements. Start with this line.

JavaScript
btn.ariaDescribedByElements
CallWhat it does
btn.ariaDescribedByElementsPrimary signature.

Built into the browser. Read or assign el.ariaDescribedByElements — no import required.

Library declarations
JavaScript
btn.ariaDescribedByElements

Parameters

ParameterDescription
Described elementRequired. Button, input, region, ...
Description elementsRequired. Plain-text help / hints / warnings

Return Value

Return ValueDescription
*The current value of el.ariaDescribedByElements.

JavaScript Examples

Example 1 — Read Description Elements

MDN-style: resolve aria-describedby ids and join their text.

JavaScript
const btn = document.querySelector("button");

if ("ariaDescribedByElements" in Element.prototype) {
  const els = btn.ariaDescribedByElements;
  const text = els.map((e) => e.textContent.trim()).join(" ");
  console.log(text);
}
Try It Yourself

How It Works

  1. Select the control with aria-describedby ids.
  2. Feature-detect the property (Newly available).
  3. Read the array of description elements.
  4. Join textContent with spaces for the accessible description.

Example 2 — Set Without Ids

Assign Element references directly; targets do not need an id.

JavaScript
const btn = document.getElementById("trash");
const d1 = document.getElementById("trash-desc1");
const d2 = document.getElementById("trash-desc2");

btn.ariaDescribedByElements = [d1, d2];
console.log(btn.ariaDescribedByElements.length); // 2
console.log(btn.getAttribute("aria-describedby")); // null
Try It Yourself

How It Works

  1. Grab the description nodes as Element objects.
  2. Assign an array. The browser copies it.
  3. Attribute clears. MDN: setting the property clears aria-describedby.
  4. Relationship remains via the property for AT.

Example 3 — Feature-Detect Fallback

Support older browsers with the classic id-string attribute.

JavaScript
function getDescribedBy(el) {
  if ("ariaDescribedByElements" in Element.prototype) {
    return Array.from(el.ariaDescribedByElements);
  }
  const ids = (el.getAttribute("aria-describedby") || "").trim().split(/\s+/);
  return ids.map((id) => document.getElementById(id)).filter(Boolean);
}

const els = getDescribedBy(document.querySelector("button"));
console.log(els.map((e) => e.textContent.trim()).join(" "));
Try It Yourself

How It Works

  1. Prefer the property when supported.
  2. Else parse ids from aria-describedby.
  3. Resolve with getElementById and drop missing ids.
  4. Join text the same way in both paths.

Browser Support

Element.ariaDescribedByElements is Baseline Newly available (MDN: since April 2025). It is not Deprecated, Experimental, or Non-standard — still feature-detect for older clients.

✓ Baseline Newly available

Element.ariaDescribedByElements

Array of elements that provide an accessible description. Flexible alternative to aria-describedby id strings; assigned elements need no id.

New Newly available (Apr 2025)
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Android WebView Supported · Modern WebView
Full support
ariaDescribedByElements New

Bottom line: Use for button/input help text. Join element text for the description string. Detect support; fall back to aria-describedby ids when needed.

Frequently Asked Questions

An array of HTMLElement subclasses that provide an accessible description for the element. Join their inner text with spaces to form the description string (MDN).
No. MDN marks Element.ariaDescribedByElements as Baseline Newly available (since April 2025). It is not Deprecated, Experimental, or Non-standard. Feature-detect on older browsers.
The attribute uses space-separated id strings. The property uses Element references. Assigned elements do not need an id. Setting the property clears the corresponding attribute (MDN).
A label names the control (ariaLabelledByElements). A description adds longer help text — warnings, hints, or extra context (MDN).
No. When read, the array is static and read-only. When written, the assigned array is copied — later changes to that array do not update the property (MDN).
When the associated content is extensive, structured, or needs navigation — use aria-details / ariaDetailsElements instead of a plain-text description (MDN).

Next: ariaDescription

Learn the Element property that reflects aria-description as a plain string.

ariaDescription tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

10 people found this page helpful