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

Screen Reader Support

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

• WAI-ARIA 1.2 Specification
  Refer to the notes from the WAI-ARIA 1.2 specification for more information on aria-level.
• A11Y Support
  The screenreader compatibility for each of the ARIA attributes is taken from the A11Y Support. Please refer to the original source if screenreader compatibility is updated for aria-level.
• MDN Web Docs
  The browser compatibility for each of the ARIA attributes is taken from the MDN Web Docs. Please refer to the original source if browser compatibility is updated for aria-level.