What is the aria-level attribute?
aria-level allows authors to define an element's level within a hierarchy so assistive technology can understand that structure.
The value must be a whole number starting at 1. An item at the first level uses 1, an item nested under it uses 2, and an item nested under that uses 3.
Where it can be used
- Elements with
role="heading", wherearia-levelis used to set the heading level. - Rows inside a
treegrid, wherearia-levelcan identify the level of each row. - Tree items, where
aria-levelcan identify their level within the tree. - Some newer or less common roles, such as
commentandassociationlistitemkey.
Where it shouldn't be used
- Native heading elements such as
<h1>to<h6>don't need it, their level is already set by the element name. - On roles that don't support
aria-level, such aslistitemoroption. - Where the structure already makes the level clear, such as properly nested tree items.
- As a substitute for creating the correct hierarchy.
aria-leveltells assistive technology the level of an item; it doesn't create the relationships between items.
Let's look at three uses for aria-level.
Example 1: creating a heading
Imagine content is being added to a page from a CMS, a content feed or an API.
The content is just a string of text with no indication of what heading level it should use.
In cases like this, role="heading" and aria-level can be used to give the content meaningful heading structure for assistive technology.
<div role="heading" aria-level="2">
This behaves like a heading, level 2
</div>View Example 1 on the testing page
Example 2: headings inside cards
Imagine a related content card that gets its title from a CMS or API. As with the previous example, the title is just a string, with no heading level attached to it.
The same card could be used in different parts of the same page.
aria-level allows you to define a heading level for the title content based on the hierarchy in that section.
In one place, its title might need to be a level 2 heading. In another, it might need to be level 3.
In the first example, the card heading is set to level 2:
<div class="card">
<div role="heading" aria-level="2">
Related article
</div>
</div>The same card could use level 3 in another part of the page:
<div class="card">
<div role="heading" aria-level="3">
Related article
</div>
</div>View Example 2 on the testing page
Example 3: aria-level in a treegrid
aria-level can also be used on rows inside a treegrid.
A treegrid can show hierarchical data in rows and columns. The rows may sit one after another in the DOM, with no nested hierarchy, even when they appear visually nested.
In this case, aria-level tells assistive technology the level of each row.
For example, in a file browser:
- Row 1: "Reports" is at level
1. - Row 2: "Archive", a folder inside "Reports", is at level
2. - Row 3: "Q1 report.docx", a file inside "Archive", is at level
3.
The hierarchy comes from the aria-level value on each row rather than from nested HTML.
<div role="row" aria-level="1" aria-expanded="true">
<span role="gridcell">Reports</span>
</div>
<div role="row" aria-level="2" aria-expanded="true">
<span role="gridcell">Archive</span>
</div>
<div role="row" aria-level="3">
<span role="gridcell">Q1 report.docx</span>
</div>A native table is usually the better choice for flat data. But a treegrid is useful when the data has a hierarchy, multiple columns and interactive keyboard navigation between cells.
View Example 3 on the testing page
Is there really no limit?
The ARIA specification sets a minimum value of 1 for aria-level, but does not set a maximum.
In practice, support for heading levels above 6 can vary:
On elements with role heading, values for aria-level above 6 can create difficulties for users. Also, at the time of this writing, most combinations of user agents and assistive technologies only support aria-level integers 1-9 on headings.
Chromium falls back to 6 for higher values.
These limits are documented for headings. It is unclear whether they also affect aria-level on treegrid rows.
Takeaway
aria-level can be used to provide hierarchy when semantic markup and structure are not available.