JavaScript Element ariaLabel Property

What You’ll Learn

Element.ariaLabel is an instance property that reflects the aria-label attribute. Learn how it supplies an accessible name as a string (or null), when to use it for icon-only controls, and how to get or set it from JavaScript—with five examples and try-it labs.

Introduction

Every interactive control needs an accessible name. A button that only shows X may be clear visually, but a screen reader needs a spoken name like “Close” or “Close dialog”.

aria-label provides that name as a string. ariaLabel is the JavaScript reflection of that attribute.

const el = document.getElementById("close-button");
console.log(el.ariaLabel); // "Close"
el.ariaLabel = "Close dialog";

Understanding the Property

MDN: the ariaLabel property of the Element interface reflects the value of the aria-label attribute, which defines a string value that labels the current element.

• Reflected attribute — mirrors aria-label.
• Get / set — readable and writable string (or null).
• Accessible name — helps AT announce what the control is.
• Baseline — widely available since October 2023 (MDN).

📝 Syntax

ariaLabel

Value

A string or null.

📋 MDN Example Shape

MDN starts with aria-label="Close" on an icon-style button, then updates it to "Close dialog":

<button aria-label="Close" id="close-button">X</button>

let el = document.getElementById("close-button");
console.log(el.ariaLabel); // "Close"
el.ariaLabel = "Close dialog";
console.log(el.ariaLabel); // "Close dialog"

Examples Gallery

Examples follow MDN Element: ariaLabel. Labs use a close-button style control so you can safely read and write the property.

const el = document.getElementById("close-button");
console.log(el.ariaLabel);

// HTML includes: aria-label="Close"

Close

let el = document.getElementById("close-button");
console.log(el.ariaLabel); // "Close"
el.ariaLabel = "Close dialog";
console.log(el.ariaLabel); // "Close dialog"

Close
Close dialog

const btn = document.createElement("button");
btn.textContent = "☰";
document.body.appendChild(btn);

btn.ariaLabel = "Open menu";
console.log({
  ariaLabel: btn.ariaLabel,
  attr: btn.getAttribute("aria-label")
});

{
  "ariaLabel": "Open menu",
  "attr": "Open menu"
}

const el = document.createElement("button");
el.textContent = "X";
el.setAttribute("aria-label", "Close");
document.body.appendChild(el);

el.ariaLabel = "Close dialog";
console.log({
  fromProperty: el.ariaLabel,
  fromAttribute: el.getAttribute("aria-label"),
  same: el.ariaLabel === el.getAttribute("aria-label")
});

{
  "fromProperty": "Close dialog",
  "fromAttribute": "Close dialog",
  "same": true
}

console.log({
  supported: "ariaLabel" in Element.prototype,
  type: "string | null",
  tip: "Prefer visible labels; use aria-label for icon-only controls",
  status: "Baseline Widely available (MDN)"
});

{
  "supported": true,
  "type": "string | null",
  "tip": "Prefer visible labels; use aria-label for icon-only controls",
  "status": "Baseline Widely available (MDN)"
}

🚀 Common Use Cases

• Icon-only close, menu, search, or settings buttons.
• Updating names when a control’s action changes (open ↔ close).
• Naming landmark-like regions that lack a visible heading.
• Giving meaningful names to custom widgets with sparse visible text.
• Keeping script and markup aligned without manual setAttribute.

🔧 How It Works

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available).
• Value is a string or null (MDN).
• Prefer visible labels when possible; use aria-label for icon-only or unclear text.
• Related: ariaLabelledByElements, ariaBrailleLabel, EventTarget, JavaScript hub.

💡 Best Practices