JavaScript Element ariaBrailleRoleDescription Property

What You’ll Learn

Element.ariaBrailleRoleDescription is an instance property that reflects the aria-brailleroledescription attribute. Learn how it shortens a custom aria-roledescription for braille, when to use it, and how to get or set it from JavaScript—with five examples and try-it labs.

Introduction

Sometimes you give an element a custom role description with aria-roledescription—for example calling an article a “slide” in a slideshow. Screen readers speak that word. Braille displays may need a shorter form.

That is what aria-brailleroledescription is for. The DOM property ariaBrailleRoleDescription lets you read and update the same value from JavaScript.

const article = document.getElementById("article");
console.log(article.ariaBrailleRoleDescription); // e.g. "sld"
article.ariaBrailleRoleDescription = "sd";

Understanding the Property

MDN: the ariaBrailleRoleDescription property of the Element interface reflects the value of the aria-brailleroledescription attribute, which defines the ARIA braille role description of the element.

It may provide an abbreviated version of aria-roledescription. Use it only when aria-roledescription is present and, in rare cases, too verbose for braille.

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

📝 Syntax

ariaBrailleRoleDescription

Value

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

📋 Slideshow Slide (MDN Shape)

MDN models a slideshow slide with spoken role description "slide" and braille contraction "sld":

<article
  id="article"
  aria-roledescription="slide"
  aria-brailleroledescription="sld"
  aria-labelledby="slide1heading">
  <h1 id="slide1heading">Welcome to my talk</h1>
</article>

Related braille property: ariaBrailleLabel (for the accessible name, not the role description).

📚 When to Use (and When Not To)

• Only when aria-roledescription is already present.
• Only when that description is too verbose for braille (rare).
• Prefer a short, recognizable contraction (MDN: slide → sld).
• Do not set a braille role description without a spoken role description.
• Do not invent custom roles lightly—aria-roledescription itself is already advanced.

Examples Gallery

Examples follow MDN Element: ariaBrailleRoleDescription. Labs use a slideshow <article> so you can safely read and write the property.

const article = document.getElementById("article");
console.log(article.ariaBrailleRoleDescription);

// HTML includes: aria-brailleroledescription="sld"

sld

const article = document.getElementById("article");
console.log(article.ariaBrailleRoleDescription); // sld
article.ariaBrailleRoleDescription = "sd";
console.log(article.ariaBrailleRoleDescription); // sd

sld
sd

const slide = document.createElement("article");
slide.setAttribute("aria-roledescription", "slide");
slide.ariaBrailleRoleDescription = "sld";
document.body.appendChild(slide);

console.log({
  roleDescription: slide.getAttribute("aria-roledescription"),
  brailleRoleDescription: slide.ariaBrailleRoleDescription
});

{
  "roleDescription": "slide",
  "brailleRoleDescription": "sld"
}

const el = document.createElement("article");
el.setAttribute("aria-roledescription", "slide");
el.setAttribute("aria-brailleroledescription", "sld");
document.body.appendChild(el);

el.ariaBrailleRoleDescription = "sd";
console.log({
  fromProperty: el.ariaBrailleRoleDescription,
  fromAttribute: el.getAttribute("aria-brailleroledescription"),
  same: el.ariaBrailleRoleDescription === el.getAttribute("aria-brailleroledescription")
});

{
  "fromProperty": "sd",
  "fromAttribute": "sd",
  "same": true
}

console.log({
  supported: "ariaBrailleRoleDescription" in Element.prototype,
  requires: "aria-roledescription must be present",
  tip: "Only when role description is too verbose for braille",
  status: "Baseline Newly available (MDN, Sep 2024)"
});

{
  "supported": true,
  "requires": "aria-roledescription must be present",
  "tip": "Only when role description is too verbose for braille",
  "status": "Baseline Newly available (MDN, Sep 2024)"
}

🚀 Common Use Cases

• Slideshow / carousel slides with a custom “slide” role description.
• Complex widgets whose aria-roledescription is long for braille cells.
• Updating a braille role contraction when localization changes.
• 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).
• Requires aria-roledescription; use only when that value is too verbose for braille.
• Different from ariaBrailleLabel (name vs role description).
• Related: ariaBusy, ariaBrailleLabel, EventTarget, JavaScript hub.

💡 Best Practices