JavaScript Element ariaDetailsElements Property

What You’ll Learn

Element.ariaDetailsElements is an instance property that holds an array of elements providing accessible details. Learn how it relates to aria-details, how details differ from a shorter description, and how to get or set the relationship from JavaScript—with five examples and try-it labs.

Introduction

Sometimes a control needs richer related content than a short description—extra paragraphs, structured help, or longer explanation that users may want to explore. ARIA exposes that link with aria-details.

ariaDetailsElements is the modern element-reference form: you work with real DOM nodes instead of only managing id strings. Accessible details are similar to an accessible description, but typically more verbose.

const details = button.ariaDetailsElements;
const text = details.map((e) => e.textContent.trim()).join(" ");
console.log(text);

Understanding the Property

MDN: the ariaDetailsElements property of the Element interface is an array containing the element (or elements) that provide an accessible details for the element it is applied to. The accessible details are similar to the accessible description (see ariaDescribedByElements), but provide more verbose information.

• Get / set — read or assign an array of elements.
• Flexible alternative to the aria-details attribute.
• No id required on detail nodes when you set the property (MDN).
• Reflection — reads valid in-scope id refs from the attribute; setting the property clears the attribute.

📝 Syntax

ariaDetailsElements

Value

An array of subclasses of HTMLElement. The inner text of these elements can be joined with spaces to get the accessible details.

• When read, the returned array is static and read-only.
• When written, the assigned array is copied—later edits to that array do not change the property.

⚖️ Property vs aria-details Attribute

📋 Button With Details (MDN Shape)

MDN’s example links a button to two detail spans via aria-details:

<button aria-details="details1 details2">Button text</button>

<span id="details1">Details 1 information about the element.</span>
<span id="details2">Details 2 information about the element.</span>

Related properties: ariaDescribedByElements (shorter description) and ariaDescription (inline description string).

Examples Gallery

Examples follow MDN Element: ariaDetailsElements. Labs feature-detect first so older browsers still show a clear message.

if ("ariaDetailsElements" in Element.prototype) {
  console.log("ariaDetailsElements is supported");
} else {
  console.log("ariaDetailsElements not supported by browser");
}

ariaDetailsElements is supported

const buttonElement = document.querySelector("button");

console.log("aria-details:", buttonElement.getAttribute("aria-details"));

if ("ariaDetailsElements" in Element.prototype) {
  const buttonElements = buttonElement.ariaDetailsElements;
  console.log("count:", buttonElements.length);
  const text = buttonElements.map((e) => e.textContent.trim()).join(" ");
  console.log("Accessible details:", text.trim());
} else {
  console.log("ariaDetailsElements not supported by browser");
}

aria-details: details1 details2
count: 2
Accessible details: Details 1 information about the element. Details 2 information about the element.

const btn = document.createElement("button");
const d1 = document.createElement("span");
const d2 = document.createElement("span");
btn.textContent = "Learn more";
d1.textContent = "Section A: long-form help about this control.";
d2.textContent = "Section B: extra related information.";
document.body.append(btn, d1, d2);

if ("ariaDetailsElements" in Element.prototype) {
  btn.ariaDetailsElements = [d1, d2];
  console.log({
    count: btn.ariaDetailsElements.length,
    attrAfterSet: btn.getAttribute("aria-details"),
    text: btn.ariaDetailsElements.map((e) => e.textContent).join(" ")
  });
} else {
  console.log("ariaDetailsElements not supported by browser");
}

{
  "count": 2,
  "attrAfterSet": null,
  "text": "Section A: long-form help about this control. Section B: extra related information."
}

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

console.log({
  fromAttribute: btn.getAttribute("aria-details"),
  supported: "ariaDetailsElements" in Element.prototype,
  fromProperty: "ariaDetailsElements" in Element.prototype
    ? btn.ariaDetailsElements.map((el) => el.id)
    : null
});

{
  "fromAttribute": "details1 details2",
  "supported": true,
  "fromProperty": ["details1", "details2"]
}

console.log({
  supported: "ariaDetailsElements" in Element.prototype,
  tip: "Returned array is static/read-only; assigned arrays are copied",
  pairsWith: "ariaDescribedByElements for shorter descriptions",
  status: "Baseline Newly available (MDN, Apr 2025)"
});

{
  "supported": true,
  "tip": "Returned array is static/read-only; assigned arrays are copied",
  "pairsWith": "ariaDescribedByElements for shorter descriptions",
  "status": "Baseline Newly available (MDN, Apr 2025)"
}

🚀 Common Use Cases

• Controls linked to longer help panels or documentation sections.
• Complex widgets that need verbose related content beyond a short description.
• Dynamic UIs that attach detail nodes without assigning ids.
• Keeping script and markup aligned without manual setAttribute.
• Custom elements via ElementInternals.ariaDetailsElements.

🔧 How It Works

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Newly available, Apr 2025).
• Feature-detect on older browsers.
• Returned arrays are static; assigned arrays are copied.
• Related: ariaDisabled, ariaDescription, EventTarget, JavaScript hub.

💡 Best Practices