Using role=heading to identify headings



For the history of this technique, see Using role=heading. Attempting to include doublequote characters in the title broke the wiki.

  • 4th Nov, Ready for TF review.
  • WG survey 14 Jan 2013, returned to TF
    • Add use cases:
      • where retrofitting a site where can't change dom because of scripts that depend on existing hierarchy
      • h7 equivalent (AT supported)

User Agent Notes [To be published separately]

  • Jaws 13 and higher supports this technique.
  • NVDA 2012.3 supports this technique.


This technique applies to HTML with WAI-ARIA.

This technique relates to Success Criterion (SC) 1.3.1. (Info and relationships):


The purpose of this technique is to provide a way for Assistive Technologies (AT) to identify a piece of content as a heading. Applying role="heading" to an element causes an AT (like a screen reader) to treat it as though it were a heading.

If there is more than one heading on the page and the heading hierarchy is defined through the visual presentation, the aria-level attribute should be used to indicate the hierarchical level of the heading.

When possible, use native heading mark-up directly. For example, it is preferable to use <h1> rather than using <div role="heading" aria-level="1">. However, the use of the heading role, instead of heading mark-up, may be necessary, for example, when retrofitting a legacy site where scripts depend on the existing element hierarchy.

The use of the heading role and nesting levels is discussed in WAI-ARIA 1.0 Authoring Practices.


Example 1

This example demonstrates how to implement simple headings using role="heading" when retrofitting a legacy site where scripts depend on the existing element hierarchy or the level is unknown for example where web content is syndicated from various sources and there is no a priori knowledge of what the final presentation will be.

<div role="heading">Global News items</div>
... a list of global news with editorial comment....

<div role="heading">Local News items</div>
... a list of local news, with editorial comment ...

Example 2

This example demonstrates how to implement a level 7 heading using role="heading" and the aria-level attribute. Since HTML only supports headings through level 6, there is no native element to provide these semantics.

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


Related Techniques

  • H42: Using h1-h6 to identify headings
  • H69: Providing heading elements at the beginning of each section of content
  • G141: Organizing a page using headings
  • F2: Failure of Success Criterion 1.3.1 due to using changes in text presentation to convey information without using the appropriate markup or text



  1. Examine each element with the attribute role="heading".
  2. Determine whether the content of the element is appropriate as a heading.
  3. If the element has an aria-level attribute, determine whether the value is the appropriate hierarchical level.

Expected results

  • Check #2 and #3 is true.