JavaScript Element ariaLevel Property

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

Definition

In JavaScript, ariaLevel reflects the aria-level attribute: a string integer that defines the hierarchical level of an element within a structure (MDN) — for example a heading level or a tree depth.

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

Syntax

Use el.ariaLevel. Start with this line.

JavaScript
element.ariaLevel
CallWhat it does
element.ariaLevelPrimary signature.

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

Library declarations
JavaScript
element.ariaLevel

Parameters

ParameterDescription
ValueRequired. String integer ≥ 1
Custom elementsOptional. ElementInternals.ariaLevel

Return Value

Return ValueDescription
*The current value of el.ariaLevel.

JavaScript Examples

Example 1 — Get and Set (MDN)

Read the current level, then update it to "2".

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

How It Works

  1. Select the element. It already has aria-level="1".
  2. Read ariaLevel. Returns the string "1".
  3. Assign "2". Updates the reflected attribute.
  4. Read again. Confirms the new hierarchical level.

Example 2 — role="heading" + Level

Declare an ARIA heading level when you cannot use a native <hn>.

JavaScript
const title = document.getElementById("section-title");
title.setAttribute("role", "heading");
title.ariaLevel = "3";
console.log(title.role, title.ariaLevel);
Try It Yourself

How It Works

  1. Set the role. heading tells AT to treat it as a heading.
  2. Set ariaLevel. Required for the heading role (ARIA).
  3. Use a string integer. Depth increases as nesting deepens.
  4. Prefer <h3> in normal documents when you can.

Example 3 — Property Reflects the Attribute

Show that ariaLevel and aria-level stay in sync.

JavaScript
const el = document.getElementById("main-heading");
el.ariaLevel = "4";
console.log(el.getAttribute("aria-level")); // "4"
el.setAttribute("aria-level", "1");
console.log(el.ariaLevel); // "1"
Try It Yourself

How It Works

  1. Write via the property. Attribute updates immediately.
  2. Read via getAttribute. Same value as ariaLevel.
  3. Write via the attribute. Property reflects the change.
  4. Keep values as digit strings (not numbers like 2 without quotes in assignment intent — use "2").
Compatibility

Browser Support

Element.ariaLevel is marked Baseline Widely available on MDN (since October 2023). Logos use the shared browser-image-sprite.png sprite from this project.

✓ Baseline · Widely available

Element ariaLevel

Reflects aria-level — hierarchical level as a string integer.

Widely Available
Google Chrome Full support · Desktop & Mobile
Full support
Mozilla Firefox Full support · Desktop & Mobile
Full support
Apple Safari Full support · macOS & iOS
Full support
Microsoft Edge Full support · Chromium
Full support
Opera Full support · Modern versions
Full support
Internet Explorer No Element.ariaLevel
Not supported
ariaLevel Baseline support

Bottom line: Safe in modern browsers. Prefer h1–h6 for document headings; use ariaLevel with role="heading" or tree-like UIs when needed. See the MDN Element.ariaLevel reference.

Frequently Asked Questions

It reflects the aria-level attribute as a string containing an integer, which defines the hierarchical level of an element within a structure (MDN).
No. MDN marks Element.ariaLevel as Baseline Widely available (since October 2023). It is not Deprecated, Experimental, or Non-standard.
A string containing an integer greater than or equal to 1, for example "1", "2", or "3".
No when you can avoid it. MDN: where possible use an HTML h1 or other correct heading level — they have built-in semantics and do not require ARIA attributes.
When you use role="heading" (required with aria-level) or other hierarchical structures (for example tree rows) and the DOM ancestry cannot express the level alone.
Yes. Reading and writing ariaLevel updates the reflected aria-level attribute.

Next: Element ariaLive

Learn how live regions announce dynamic updates to assistive tech.

ariaLive 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)

11 people found this page helpful

JavaScript Element ariaLabelledByElements Property JavaScript Element ariaLive Property