ElementInternals: ariaLabelledByElements property

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 a static and read-only. When written, the assigned array is copied: subsequent changes to the array do not affect the value of the property.

The property is a flexible alternative to using the aria-labelledby attribute to set the accessible name. Unlike aria-labelledby, the elements assigned to this property do not have to have an id attribute.

The property reflects the element's aria-labelledby attribute when it is defined, but only for listed reference id values that match valid in-scope elements. If the property is set, then the corresponding attribute is cleared. For more information about reflected element references and scope see Reflected element references in the Reflected attributes guide.

This example shows how ariaLabelledByElements can be used to programmatically get a label defined using aria-labelledby within the shadow root.

HTML

The HTML defines two <span> elements and references their ids in the aria-labelledby attribute of an <input>. The accessible name of the <input> is therefore the concatenation of the inner text of the two referenced elements.

<div id="host">
  <template shadowrootmode="open">
    <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>
  </template>
</div>

<pre id="log"></pre>

#log {
  height: 70px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

JavaScript

The code below first checks whether the ariaLabelledByElements is supported and if not, logs the result and exits. If the property is supported it first logs the value of the property. It then iterates through the returned elements, concatenating their inner text, and logs the resulting accessible name of the element.

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

// Get access to the input within shadowRoot
const hostElement = document.getElementById("host");
const shadowRoot = hostElement.shadowRoot;
const inputElement = shadowRoot.querySelector("input");

// Feature test for ariaLabelledByElements
if ("ariaLabelledByElements" in ElementInternals.prototype) {
  // Get and log attribute that provides the accessible name
  log(`aria-labelledby: ${inputElement.getAttribute("aria-labelledby")}`);

  // Get and log elements that provide the accessible name
  const labelElements = inputElement.ariaLabelledByElements;
  log(`ariaLabelledByElements: ${labelElements}`);

  // Log inner text of elements to get accessible name
  const text = labelElements.map((e) => e.textContent.trim()).join(" ");
  log(`Accessible name: ${text.trim()}`);
} else {
  log("ariaLabelledByElements not supported by browser");
}

Result

The log below shows the output of the above code. This should show the array of referenced HTMLSpanElement elements, and the resulting accessible name from their inner text.

• aria-labelledby attribute
• Element.ariaLabelledByElements
• Reflected element references in the Attribute reflection guide.