ARIA: heading role

 {{ariaref}}

The heading role defines this element as a heading to a page or section. To give the page more structure, a level should also be provided to indicate relationships between sections.

<div role="heading" aria-level="1">This is a main page heading</div>

This defines the text in the div to be the main heading of the page, indicated by being of level 1 via the aria-level attribute.

Description

The heading role indicates to assistive technologies that this element should be treated like a heading. Screen readers would, for example, read the text and indicate that this text is formatted like a heading. In addition, a level should be indicated to tell assistive technologies which part of the page structure this heading represents. A level 1 heading usually indicates the main heading of a page, a level 2 heading the first sub section, a level 3 would then be a sub section of that, etc.

Associated WAI-ARIA Roles, States, and Properties

aria-level
The aria-level attribute specifies the level this heading is at in the document structure. If no level is present, a value of 2 is the default.

Keyboard Interactions

This role does not require any special keyboard navigation. As with any heading, giving it an ID makes sure it can be referenced from anchor links. and thus becomes accessible via the keyboard.

Required JavaScript features

Required Event Handlers
None
Changing attribute values
Usually not required, unless dynamically inserting content, in which case the newly added headings need aria-level attributes whose values are consistent with the rest of the document structure.

Instead of using a <div> or <span> with a heading role and aria-level, consider using a native <h1> through <h6> element instead to indicate that this text is a heading, and what part of the structure it represents.

Examples

The following shows a typical page structure.

<div id="container">
<div role="heading" aria-level="1">The main page heading</div>
<p>This article is about showing a page structure.</p>
<div role="heading" aria-level="2">Introduction</div>
<p>An introductory text.</p>
<div role="heading" aria-level="2">Chapter 1</div>
<p>Text</p>
<div role="heading" aria-level="3">Chapter 1.1</div>
<p>More text in a sub section.</p>
...</div>

However, instead, you should do:

<div id="container">
<h1>The main page heading</h1>
<p>This article is about showing a page structure.</p>
<h2>Introduction</h2>
<p>An introductory text.</p>
<h2>Chapter 1</h2>
<p>Text</p>
<h3>Chapter 1.1</h3>
<p>More text in a sub section.</p>
...</div>

Accessibility concerns

If you have to use the heading role and aria-level attribute, to stay consistent with HTML, make sure to not go over level 6 with the levels. Although theoretically you can go higher, and some screen readers may support it, the results can be unpredictable with other browser/screen reader combinations.

Best practices

The best way to use this role is to not use it at all, and instead use the native heading tags <h1> through <h6> as shown in the example above. The heading role and aria-level attribute should really only be used if you retrofit accessibility on some legacy code that you cannot make major changes to.

Added benefits

None.

Specifications

Specification Status
Accessible Rich Internet Applications (WAI-ARIA) 1.1
The definition of 'heading' in that specification.
Recommendation

Precedence order

The heading role overrides the native semantic meaning of the leement it is being used on. The aria-level attribute, in addition, provides the information what level of heading is being exposed.

Screen reader support

TBD

See also

Document Tags and Contributors

Contributors to this page: mdnwebdocs-bot, estelle, jswisher, MarcoZ
Last updated by: mdnwebdocs-bot,