This Wiki page is edited by participants of the WCAG Working Group. It does not necessarily represent consensus and it may have incorrect information or information that is not supported by other Working Group participants, WAI, or W3C. It may also have some very useful information.
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)
- Add use cases:
- Reviewed by TF in Techniques Task Force: ARIA techniques for 8 Aug 2013
- Reviewed by WG in WCAG review of Techniques Task Force: ARIA techniques for 10 September 2013
- Reviewed by WG on October 29 call and accepted as amended.
- Added to XML by AWK 2014/1/2
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
When possible, use native heading mark-up directly. For example, it is preferable
<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.
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 ...
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> ... <h6>Apples</h6> <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>
- WAI-ARIA Authoring Practices
- heading, The Roles Model, Accessible Rich Internet Applications (WAI-ARIA) 1.0
- 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
- Examine each element with the attribute role="heading".
- Determine whether the content of the element is appropriate as a heading.
- If the element has an aria-level attribute, determine whether the value is the appropriate hierarchical level.
- Check #2 and #3 is true.