JavaScript Element ariaLabelledByElements Property

What You’ll Learn

Element.ariaLabelledByElements is an instance property that holds an array of elements providing an accessible name. Learn how it relates to aria-labelledby, why label targets do not need an id when you set the property, and how to get or set the relationship from JavaScript—with five examples and try-it labs.

Introduction

Every control needs an accessible name. Often that name already exists as visible text on the page—a heading, a caption, or a short instruction next to a field. ARIA can point to those nodes with aria-labelledby.

ariaLabelledByElements is the modern element-reference form: you work with real DOM nodes instead of only managing id strings. Join their text with spaces to get the accessible name.

const labelledBy = input.ariaLabelledByElements;
const text = labelledBy.map((e) => e.textContent.trim()).join(" ");
console.log(text);

Understanding the Property

MDN: the ariaLabelledByElements property of the Element interface is an array containing the element (or elements) that provide an accessible name for the element it is applied to. It is similarly intended to provide a label for elements that do not have a standard method for defining their accessible name.

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

📝 Syntax

ariaLabelledByElements

Value

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

• 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-labelledby Attribute

📋 Input Labelled by Spans (MDN Shape)

MDN’s example links an input to two spans via aria-labelledby. The accessible name is the concatenation of both spans’ text, separated by a space:

<span id="label_1">Street name</span>
<input aria-labelledby="label_1 label_2" />
<span id="label_2">(just the name, no "Street" or "Road" or "Place")</span>

Related naming APIs: ariaLabel (string name) and ariaDescribedByElements (longer help text, not the short name).

Examples Gallery

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

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

ariaLabelledByElements is supported

const inputElement = document.querySelector("input");

console.log("aria-labelledby:", inputElement.getAttribute("aria-labelledby"));

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

aria-labelledby: label_1 label_2
count: 2
Accessible name: Street name (just the name, no "Street" or "Road" or "Place")

const input = document.createElement("input");
const a = document.createElement("span");
const b = document.createElement("span");
a.textContent = "Email address";
b.textContent = "(work account)";
document.body.append(a, input, b);

if ("ariaLabelledByElements" in Element.prototype) {
  input.ariaLabelledByElements = [a, b];
  console.log({
    count: input.ariaLabelledByElements.length,
    attrAfterSet: input.getAttribute("aria-labelledby"),
    text: input.ariaLabelledByElements.map((e) => e.textContent).join(" ")
  });
} else {
  console.log("ariaLabelledByElements not supported by browser");
}

{
  "count": 2,
  "attrAfterSet": null,
  "text": "Email address (work account)"
}

const input = document.querySelector("input");

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

{
  "fromAttribute": "label_1 label_2",
  "supported": true,
  "fromProperty": ["label_1", "label_2"]
}

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

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

🚀 Common Use Cases

• Inputs labelled by multiple visible text fragments.
• Containers or custom roles that need a name from nearby headings.
• Dynamic UIs that attach label nodes without assigning ids.
• Overriding a default accessible name with explicit label elements (MDN: takes precedence).
• Custom elements via ElementInternals.ariaLabelledByElements.

🔧 How It Works

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline 2025—feature-detect older browsers).
• Takes precedence over other methods of setting the ARIA label (MDN).
• Returned arrays are static/read-only; assigned arrays are copied.
• Related: ariaLevel, ariaDescribedByElements, EventTarget, JavaScript hub.

💡 Best Practices