heading
Marks an element as a heading. Use <h1>–<h6> first — they carry the right semantics and a correct level for free. Reach for role="heading" only when you have to upgrade an element that cannot be an <h*>.
When to use
Always reach for <h1> through <h6> first. The native heading element gives you the role, the level, and a built-in user-agent stylesheet.
role="heading" is appropriate only when you cannot use a native heading — typically inside a constrained CMS that renders all text as <p> or <div>. When you do, you MUST set aria-level to a number from 1 through 6 (or higher, but assistive tech ignores levels past 6 in practice).
Do not skip heading levels: an <h2> should not be followed by an <h4> without an <h3> between them. Screen-reader users navigating by heading rely on the outline being coherent.
Common failures
role="heading"with noaria-level. The role is required to carry the level.- Visually styled “headings” (large bold text) that are wrapped in
<div>or<span>with no heading role. Screen-reader users skip past them entirely. - Multiple
<h1>elements on one page when only one main heading is intended. Best practice is one<h1>per page that names the main content. - Skipping levels — jumping from
h2toh4— breaks the document outline. - Decorative text styled to look like a heading but not meant as one, marked up as a heading anyway. Confuses screen-reader navigation.
Example
<!-- Preferred -->
<h2>How to file a complaint</h2>
<!-- Only when <h2> is impossible -->
<div role="heading" aria-level="2">How to file a complaint</div>