JavaScript Element role Property

Beginner
5 min read
Updated: Nov 2026
3 examples
Property
Decorative image with the word ROLE

Definition

Element.role gets or sets the element’s explicit WAI-ARIA role — the value of the HTML role attribute (MDN). It does not return the element’s implicit role.

Read the notes below before you get or set this property. Prefer feature detection when support is limited.

Syntax

Use el.role. Start with this line.

JavaScript
element.role / = value
CallWhat it does
element.role / = valuePrimary signature.

Built into the browser. Read or assign el.role — no import required.

Library declarations
JavaScript
element.role / = value

Parameters

ParameterDescription
ClearOptional. el.role = null / remove attribute

Return Value

Return ValueDescription
*String or null

JavaScript Examples

Example 1 — Read Explicit role

Unset elements return null; an attribute returns its string.

JavaScript
const plain = document.createElement("div");
const withRole = document.createElement("div");
withRole.setAttribute("role", "button");

console.log(plain.role);    // null
console.log(withRole.role); // "button"
Try It Yourself

How It Works

  1. Create two divs. Neither has special HTML semantics like <button>.
  2. Leave one unset. role is null (no explicit attribute).
  3. Set role="button" on the other via the attribute.
  4. Read .role. You get the explicit string "button".

Example 2 — Set presentation (MDN)

Mark decorative images that have no useful alt text.

JavaScript
const images = document.querySelectorAll("img");

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

console.log(document.getElementById("deco").role);
// "presentation"
Try It Yourself

How It Works

  1. Select images. Loop every <img>.
  2. Check alt. Empty/missing alt often means decorative.
  3. Assign role = "presentation". Assistive tech can ignore it as content.
  4. Still prefer good alt for meaningful images — role is not a substitute for content.

Example 3 — Property Reflects the Attribute

Assigning role updates the HTML attribute (and the other way around).

JavaScript
const el = document.createElement("div");

el.role = "status";
console.log(el.getAttribute("role")); // "status"

el.setAttribute("role", "img");
console.log(el.role);                 // "img"
Try It Yourself

How It Works

  1. Assign the property. The role attribute appears on the element.
  2. Read via getAttribute. Same string.
  3. Change the attribute. The property updates too.
  4. Keep them in sync — either API is fine for simple cases.
Compatibility

Browser Support

Element.role is Baseline Widely available (MDN: across browsers since October 2023). Safe in modern evergreen browsers.

✓ Baseline · Widely available

Element.role

Get or set the explicit WAI-ARIA role string — null when the role attribute is not set.

92% Widely available
Google Chrome All versions · Desktop & Mobile
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Internet Explorer IE 6+ · Legacy environments
Full support
Opera All modern versions
Full support
role Excellent

Bottom line: Safe for modern production. Prefer native HTML; use role when you must expose or override semantics.

Frequently Asked Questions

It gets or sets the explicitly assigned WAI-ARIA role for an element by reflecting the HTML role attribute.
No. It returns only the explicitly set role attribute value. If an element has only an implicit role, element.role is null unless you set a role yourself.
It returns null when the element does not have an explicit role attribute.
No. MDN marks Element.role as Baseline Widely available (across browsers since October 2023). It is not Deprecated, Experimental, or Non-standard.
Yes. Assign a string such as el.role = "button" or el.role = "presentation" to update the role attribute.
No. Prefer native HTML semantics. Use an explicit role only when you have a clear accessibility reason.

Next: scrollHeight

Learn how to read an element’s full scrollable content height.

scrollHeight tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

14 people found this page helpful

JavaScript Element previousElementSibling Property JavaScript Element scrollHeight Property