JavaScript Element ariaBrailleLabel Property

What You’ll Learn

Element.ariaBrailleLabel is an instance property that reflects the aria-braillelabel attribute. Learn when a braille-specific label helps, how it differs from aria-label, and how to get or set the property from JavaScript—with five examples and try-it labs.

Introduction

Screen readers speak an element’s accessible name. Braille displays often convert that same name into braille cells. Sometimes the spoken name is long or awkward in braille—for example a star rating described as “3 out of 5 stars.”

aria-braillelabel lets you provide a shorter braille-oriented label. ariaBrailleLabel is the JavaScript reflection of that attribute.

const button = document.getElementById("button");
console.log(button.ariaBrailleLabel); // e.g. "***"
button.ariaBrailleLabel = "3*";

Understanding the Property

MDN: the ariaBrailleLabel property of the Element interface reflects the value of the aria-braillelabel attribute, which defines the ARIA braille label of the element.

Assistive technologies that present content in braille may use this label, but you should set it only when a braille-specific label improves the user experience.

• Reflected attribute — mirrors aria-braillelabel.
• Get / set — readable and writable string.
• Unconstrained string — intended to be converted into braille.
• Baseline — newly available since September 2024 (MDN).

📝 Syntax

ariaBrailleLabel

Value

A string—an unconstrained value type intended to be converted into braille.

📋 When to Use (and When Not To)

MDN’s aria-braillelabel docs stress that assistive technologies can already convert accessible names to braille. Use this attribute only when that default conversion is not the experience you want.

• The element must still have a valid accessible name (content, aria-label, etc.).
• The braille label must have real content (not empty / whitespace-only).
• It should not be identical to the accessible name.
• Localize values to match the document language.
• Do not copy aria-label into aria-braillelabel just to “be complete.”

<!-- Visible / spoken name is verbose; braille label is compact -->
<button id="button" aria-braillelabel="***">3 out of 5 stars</button>

A braille display may show something like “btn ***” instead of a long spelling of “3 out of 5 stars.”

Examples Gallery

Examples follow MDN Element: ariaBrailleLabel. Labs use a star-rating button so you can safely read and write the property.

const button = document.getElementById("button");
console.log(button.ariaBrailleLabel);

// HTML includes: aria-braillelabel="***"

***

const button = document.getElementById("button");
console.log(button.ariaBrailleLabel); // ***
button.ariaBrailleLabel = "3*";
console.log(button.ariaBrailleLabel); // 3*

***
3*

const btn = document.createElement("button");
btn.textContent = "4 out of 5 stars";
document.body.appendChild(btn);

btn.ariaBrailleLabel = "****";
console.log({
  text: btn.textContent,
  ariaBrailleLabel: btn.ariaBrailleLabel,
  attr: btn.getAttribute("aria-braillelabel")
});

{
  "text": "4 out of 5 stars",
  "ariaBrailleLabel": "****",
  "attr": "****"
}

const el = document.createElement("button");
el.textContent = "3 out of 5 stars";
el.setAttribute("aria-braillelabel", "***");
document.body.appendChild(el);

el.ariaBrailleLabel = "3*";
console.log({
  fromProperty: el.ariaBrailleLabel,
  fromAttribute: el.getAttribute("aria-braillelabel"),
  same: el.ariaBrailleLabel === el.getAttribute("aria-braillelabel")
});

{
  "fromProperty": "3*",
  "fromAttribute": "3*",
  "same": true
}

console.log({
  supported: "ariaBrailleLabel" in Element.prototype,
  tip: "Only set when accessible name is poor in braille",
  notFor: "Do not copy aria-label into aria-braillelabel",
  status: "Baseline Newly available (MDN, Sep 2024)"
});

{
  "supported": true,
  "tip": "Only set when accessible name is poor in braille",
  "notFor": "Do not copy aria-label into aria-braillelabel",
  "status": "Baseline Newly available (MDN, Sep 2024)"
}

🚀 Common Use Cases

• Compact braille for star ratings or similar symbolic UI.
• Icons / images whose spoken names are long for braille displays.
• Updating a braille label when a rating or status changes in script.
• Keeping script and markup aligned without manual setAttribute.
• Accessibility reviews for products that target braille users.

🔧 How It Works

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Newly available, Sep 2024).
• Do not duplicate aria-label into aria-braillelabel.
• The element still needs a valid accessible name.
• Related: ariaBrailleRoleDescription, ariaAutoComplete, EventTarget, JavaScript hub.

💡 Best Practices