role="heading"

What role="heading" means, and when to use it

Use heading for a heading, and always give it aria-level. The level is the whole point, because a screen reader user navigates by the heading outline and the outline is built from the levels. This role is for when you genuinely cannot use a heading element, and that is rarer than it looks.

The HTML element behind role="heading"

The h1 to h6 elements are headings and set their level from the tag name, so an h3 is level 3 with nothing added. That is one attribute you cannot forget and one fewer thing to keep in sync.

Document structure roles describe how the content is organized

These roles describe the shape of the content rather than controls somebody operates. Headings, lists, tables, figures and paragraphs, so that assistive technology users can navigate by structure instead of reading straight through.

Nearly every one of them has an HTML element that means the same thing and needs no help. Reaching for the role instead is a step backwards, because the element brings its behavior with it and the role brings none. ARIA in HTML goes further and asks conformance checkers to flag a role that only restates what the element already said.

There is one honest exception to that. Some browsers drop a list's semantics when CSS removes the markers, and ARIA in HTML says a redundant role="list" on a ul is reasonable in exactly that case.

Where role="heading" sits in the model

Inherits from

sectionhead → structure → roletype

The name can come from

Its own text, which is usually the right answer, or aria-labelledby and aria-label when the visible words will not do.

The normative definition stays with the W3C, so it cannot go stale here. heading in the ARIA specification.

How a checker tests role="heading"

Getting this one wrong is easy to assume is a 4.1.2 Name, Role, Value problem, and mostly it is not. A missing required state is first of all a WAI-ARIA conformance failure, and W3C notes that 4.1.2 is the looser test of the two, because a browser will often fall back on a value that passes it. These are the published test rules that apply.

• Element with role attribute has required states and properties
• Role attribute has valid value

The other structure roles

• application Hands every keystroke to your code instead of the screen reader. Use it only when nothing else will do.
• article A self-contained piece of content that still makes sense pulled out on its own.
• blockquote A quotation from somewhere else.
• caption The title of a table or a figure, sitting inside the thing it titles.
• cell One data cell in a table.
• code A fragment of computer code.
• columnheader A header cell that names its column.
• definition The meaning of a term.
• deletion Text that has been removed.
• directory A list of references, such as a table of contents. ARIA 1.2 deprecates it in favor of list.
• document Content meant to be read rather than operated, which puts screen readers back into reading mode.
• emphasis Text carrying stress emphasis, the meaning the em element has.
• feed A stream of articles that keeps loading more as somebody scrolls.
• figure An illustration with a caption, referred to from the text around it.
• generic The role a plain div or span already has. It exists for browsers, not for authors.
• group A set of related items that is not important enough to be a landmark and stays out of the page outline.
• img Anything built from markup that should be announced as a single image.
• insertion Text that has been added.
• list A list, which has to contain actual list items.
• listitem One entry in a list.
• math A mathematical expression.
• meter A gauge showing where a value sits in a known range, like disk usage. It is not a progress bar.
• none Strips an element's own meaning while leaving its content in place. The same role as presentation.
• note An aside or annotation about the content around it.
• paragraph A paragraph of text.
• presentation Strips an element's own meaning while leaving its content in place. The same role as none.
• row One row in a table, grid or treegrid.
• rowgroup A band of rows, the equivalent of thead or tbody.
• rowheader A header cell that names its row.
• separator A divider between sections. It becomes a control when it can be moved, and only then does it need a value.
• strong Text carrying strong importance, the meaning the strong element has.
• subscript Text set below the baseline.
• superscript Text set above the baseline.
• table Data laid out in rows and columns for reading, not for operating.
• term A word or phrase being defined.
• time A point in time or a length of it.
• toolbar A container for related controls that groups them for keyboard navigation.
• tooltip A small label that appears on hover or focus, and it should hold no controls of its own.