The HTML aria-level attribute
The aria-level attribute defines the hierarchical level of an element: a heading level, or the depth of a tree item or nested list. Value: an integer of 1 or more. Prefer native <h1>–<h6> for headings.
Overview
The aria-level attribute defines the hierarchical level of an element within a structure.
It states how deep an element sits in a hierarchy: the level of a role="heading" element, or the depth of a treeitem inside nested groups. Browsers already infer this from native <h1>-<h6> headings and from properly nested lists, so you only need it on custom structures where nothing native conveys the level.
Like all ARIA, aria-level changes only the accessibility tree (what assistive technology perceives), never the element's behavior or appearance. The first rule of ARIA applies: if a native HTML element or attribute conveys this, use that instead, and only reach for ARIA when nothing native fits.
Syntax
<div role="heading" aria-level="2">Section title</div>Values
| Value |
|---|
| An integer greater than or equal to 1. |
Example
<div role="heading" aria-level="3">Custom heading</div>Best practices
- Follow the first rule of ARIA: use a native HTML element or attribute that conveys this where one exists, rather than adding ARIA.
- Use these when the full set is not in the DOM (virtualized lists, lazy-loaded trees).
- Set aria-posinset and aria-setsize together for each item.
- For fully-rendered native lists, let the browser compute position and size instead.
Frequently asked questions
What does aria-level do?
When do I need aria-level?
Do native headings need aria-level?
<h1> through <h6> already carry their level, and a native heading is always the better choice.