JavaScript Element ariaLevel Property

What You’ll Learn

Element.ariaLevel is an instance property that reflects the aria-level attribute. Learn how it stores a hierarchical level as a string integer, when to prefer native <h1>–<h6> headings, and how to get or set the property from JavaScript—with five examples and try-it labs.

Introduction

Documents and widgets often have hierarchy: page title, section title, nested tree items. Assistive technologies need to know which level an item sits at in that structure.

aria-level carries that number as a string. ariaLevel is the JavaScript reflection of that attribute.

const el = document.getElementById("main-heading");
console.log(el.ariaLevel); // "1"
el.ariaLevel = "2";

Understanding the Property

MDN: the ariaLevel property of the Element interface reflects the value of the aria-level attribute, which defines the hierarchical level of an element within a structure.

• Reflected attribute — mirrors aria-level.
• Get / set — readable and writable string containing an integer.
• Hierarchy — level within headings, trees, and similar structures.
• Baseline — widely available since October 2023 (MDN).

📝 Syntax

ariaLevel

Value

A string containing an integer.

📋 MDN Example Shape

MDN starts with role="heading" and aria-level="1", then updates the level to "2" with the property:

<div role="heading" id="main-heading" aria-level="1">
  This is a main page heading
</div>

let el = document.getElementById("main-heading");
console.log(el.ariaLevel); // "1"
el.ariaLevel = "2";
console.log(el.ariaLevel); // "2"

Examples Gallery

Examples follow MDN Element: ariaLevel. Labs use a role="heading" element so you can safely read and write the property.

const el = document.getElementById("main-heading");
console.log(el.ariaLevel);

// HTML includes: role="heading" aria-level="1"

1

let el = document.getElementById("main-heading");
console.log(el.ariaLevel); // "1"
el.ariaLevel = "2";
console.log(el.ariaLevel); // "2"

1
2

const el = document.createElement("div");
el.setAttribute("role", "heading");
el.textContent = "Subsection title";
document.body.appendChild(el);

el.ariaLevel = "3";
console.log({
  ariaLevel: el.ariaLevel,
  attr: el.getAttribute("aria-level")
});

{
  "ariaLevel": "3",
  "attr": "3"
}

const el = document.createElement("div");
el.setAttribute("role", "heading");
el.setAttribute("aria-level", "1");
el.textContent = "This is a main page heading";
document.body.appendChild(el);

el.ariaLevel = "2";
console.log({
  fromProperty: el.ariaLevel,
  fromAttribute: el.getAttribute("aria-level"),
  same: el.ariaLevel === el.getAttribute("aria-level")
});

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

console.log({
  supported: "ariaLevel" in Element.prototype,
  type: "string containing an integer",
  tip: "Prefer native h1–h6 when possible (MDN)",
  status: "Baseline Widely available (MDN)"
});

{
  "supported": true,
  "type": "string containing an integer",
  "tip": "Prefer native h1–h6 when possible (MDN)",
  "status": "Baseline Widely available (MDN)"
}

🚀 Common Use Cases

• Custom role="heading" widgets that cannot use <h1>–<h6>.
• Updating heading level when a section moves in the document outline.
• Tree items that expose nesting depth via aria-level.
• Design-system components that render headings as non-heading tags.
• Keeping script and markup aligned without manual setAttribute.

🔧 How It Works

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available).
• Prefer native <h1>–<h6> when possible (MDN note).
• Value is a string containing an integer, not a Number type.
• Related: ariaLive, ariaLabel, EventTarget, JavaScript hub.

💡 Best Practices