WAI-ARIA: aria-level (Property)

Description

Defines the hierarchical level of an element within a structure.

This can be applied inside trees to tree items, to headings inside a document, to nested grids, nested tablists and to other structural items that may appear inside a container or participate in an ownership hierarchy. The value for aria-level is an integer greater than or equal to 1.

Levels increase with depth. If the DOM ancestry does not accurately represent the level, authors SHOULD explicitly define the aria-level attribute.

This attribute is applied to elements that act as leaf nodes within the orientation of the set, for example, on elements with role treeitem rather than elements with role group. This means that multiple elements in a set may have the same value for this attribute. Although it would be less repetitive to provide a single value on the container, restricting this to leaf nodes ensures that there is a single way for assistive technologies to use the attribute.

If the DOM ancestry accurately represents the level, the user agent can calculate the level of an item from the document structure. This attribute can be used to provide an explicit indication of the level when that is not possible to calculate from the document structure or the aria-owns attribute. User agent support for automatic calculation of level may vary; authors SHOULD test with user agents and assistive technologies to determine whether this attribute is needed. If the author intends for the user agent to calculate the level, the author SHOULD omit this attribute.

Note: In the case of a treegrid, aria-level is supported on elements with the role row, not elements with role gridcell. At first glance, this may seem inconsistent with the application of aria-level on treeitem elements, but it is consistent in that the row acts as the leaf node within the vertical orientation of the grid, whereas the gridcell is a leaf node within the horizontal orientation of each row. Level is not supported on sets of cells within rows, so the aria-level attribute is applied to the element with the role row.

Browser Compatibility For aria-level

	desktop						mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	WebView Android	Chrome Android	Firefox for Android	Opera Android	Safari on iOS	Samsung Internet
ariaLevel	ChromeFull support81	EdgeFull support81	FirefoxNo supportNo	Internet ExplorerNo supportNo	OperaFull support68	SafariFull support12.1	WebView AndroidFull support81	Chrome AndroidFull support81	Firefox for AndroidNo supportNo	Opera AndroidFull support58	Safari on iOSFull support12.2	Samsung InternetFull support13.0

Screen Reader Support For aria-level

Expectation	JAWS			Narrator	NVDA			Orca	TalkBack	VoiceOver (iOS)	VoiceOver (macOS)
	Chrome	Edge	Firefox	Edge	Chrome	Edge	Firefox	Firefox	Chrome	Safari	Safari
MUST convey the presence and value of the aria-level attribute	supported	supported	supported	supported	supported	supported	supported	supported	supported	supported	supported

aria-level Example

HTML Example for heading level 7

..
<h5>Fruit Trees</h5>...
<h6>Apples</h6>
<p>Apples grow on trees in areas known as orchards...</p>...
<div role="heading" aria-level="7">
  Jonagold/div&gt;
  <p>Jonagold is a cross between the Golden Delicious and Jonathan varieties...</p>
</div>

Characteristics

Used in Roles

• grid
• heading
• listitem
• row
• tablist

Inherits into Roles

• treegrid
• treeitem

Value

• integer
  • A numerical value without a fractional component.

Semantic HTML

Use semantic headings for heading levels 1-6.

<h1>heading text</h1>

Reference

• W3C (opens new window)
• A11Y Support
• MDN Web Docs