JavaScript Element role Property

What You’ll Learn

Element.role is an instance property that reflects the explicit ARIA role attribute on an element. Learn what it returns, how it differs from implicit roles, when it gives null, and how to update it safely with five examples and try-it labs.

Introduction

HTML elements already come with built-in meaning. For example, a native <button> is announced like a button by assistive technologies. That built-in meaning is called an implicit role.

The role attribute lets you set an explicit ARIA role when needed, and Element.role is the JavaScript property that reflects that attribute.

const box = document.getElementById("card");
console.log(box.role);   // "button" or null
box.role = "button";

Understanding the Property

MDN: the role property of the Element interface returns the explicitly set WAI-ARIA role for the element.

• Reflects the attribute — it matches the HTML role attribute.
• String or null — returns a role name, or null if not explicitly set.
• Explicit only — does not expose implicit semantics unless you assign them yourself.
• Accessibility-focused — mainly used when inspecting or updating ARIA semantics.

📝 Syntax

element.role
element.role = "button"

Value

A string containing the explicit role value, or null when no role attribute is present.

📋 MDN Accessibility Example Shape

MDN demonstrates setting a presentational role on images that have no alternate text:

const images = document.querySelectorAll("img");
images.forEach((image) => {
  if (!image.alt) {
    image.role = "presentation";
  }
});

Related learning: ariaLabel, ariaHidden, and role in HTML accessibility patterns.

Examples Gallery

Examples follow MDN Element: role. They focus on reading explicit roles, comparing missing values, and updating semantics clearly.

const box = document.getElementById("card");
console.log(box.role); // "button"

button

const button = document.querySelector("button");
console.log(button.role); // null

null

const panel = document.getElementById("panel");
panel.role = "status";
console.log(panel.role);

status

const item = document.getElementById("item");
item.role = "listitem";
console.log(item.role);
console.log(item.getAttribute("role"));

listitem
listitem

const images = document.querySelectorAll("img");
images.forEach((image) => {
  if (!image.alt) {
    image.role = "presentation";
  }
});

photo-1: null
photo-2: presentation

🚀 Common Use Cases

• Checking whether a custom widget has an explicit ARIA role.
• Assigning roles to non-native interactive patterns when necessary.
• Auditing markup to find elements with missing or unexpected explicit roles.
• Marking decorative content as presentation in accessibility cleanup code.
• Comparing JavaScript property reflection with the raw HTML attribute.

🔧 How It Works

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available).
• element.role reflects only explicit roles, not implicit native semantics.
• Use roles to improve accessibility, not to replace good semantic HTML without a reason.
• Related: ariaLabel, ariaHidden, part, JavaScript hub.

💡 Best Practices