Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 38 ยท Semantic HTML and ARIA

Headings and the Document Outline

Learn how to write headings that give screen reader users a table of contents, avoid skipped levels, choose levels by structure not size, and check an outline.

Headings are the single most useful structure on a page. Screen reader surveys consistently find that most users navigate by headings first. Press H and you hop to the next heading, press a number to jump to that level, or pull up a list of all headings. Sighted users scan the same headings visually. Writing them well helps both groups, and it helps search engines too.

In this lesson you will learn the rules for heading levels, why you should choose by structure instead of size, how to write useful heading text, and how to check the outline with a short script.

The rules

  1. One <h1> per page that names the page's topic. It usually matches the <title>.
  2. Levels reflect hierarchy: an <h2> is a section of the <h1>, an <h3> a subsection of an <h2>, and so on.
  3. Do not skip levels when going deeper. After an <h2>, the next may be <h3> or another <h2>, but not <h4>. Going back up is fine: an <h4> followed by an <h2> is a new section.
  4. Do not use headings for style. If you want large bold text that is not a heading, use CSS. If you want a heading that looks small, use CSS on a real heading.
  5. Do not leave headings empty, and avoid hiding all of them visually.

A good outline

h1 Page topic, once
h2 Main sections
h3 Subsections

Never jump from h2 straight to h4.

1 / 2

Structure, not size

Heading levels carry meaning, and font size is decoration. This is the same content in both cases, so the first is a good outline and the second a misleading one.

HTML
<!-- Good: levels describe structure; CSS controls look -->
<h1>Gardening for beginners</h1>
<h2>Soil</h2>
<h3>Testing your soil</h3>
<h2>Tools</h2>

<!-- Bad: picked for size -->
<h1>Gardening for beginners</h1>
<h4>Soil</h4>
<h2>Testing your soil</h2>
Outline viewer

All headings look the same size thanks to the CSS, so you cannot see the problem, but the outline shows that "Hand trowels" jumps from h2 to h4. A screen reader user would wonder what happened to the h3.

Writing good heading text

  • Be specific. "Pricing for teams" beats "Details".
  • Be unique within the page. Ten headings called "Learn more" are indistinguishable in a headings list.
  • Front-load the meaning, so users can decide after a couple of words.
  • Keep them short. A heading is a label, not a sentence of explanation.

Where headings live

Headings belong to the page as a whole. A widget such as a sidebar can have a heading too. For example <aside aria-labelledby="related"> with <h2 id="related">Related posts</h2> both names the landmark and shows in the headings list. When you assemble pages from components, review the whole outline, since each component author may have started at <h1> independently.

Headings in components

Reusable components cannot know which level they belong at. Common solutions include passing the level as a parameter, or computing it from the nesting context. Whatever approach you choose, test the finished page.

A component with a configurable heading level

Styling headings with CSS

Need a smaller <h2>? Style it: h2 { font-size: 1.25rem; }. Need something that looks like a heading but is not one, such as the label above a pricing card number? Use a <p> or <div> with a class. Never choose a heading element only to inherit its default size. Be careful with display: none and visibility: hidden, since they remove the heading for everyone, including screen readers. Use a visually hidden utility class if a heading should exist only for assistive technology.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How many <h1> elements should a typical page have?

    A single h1 names the page topic and matches the title, giving a clear top of the outline.
  2. 2. An <h2> is followed directly by an <h4>. Why is this a problem?

    Skipped levels suggest missing content in screen reader headings lists.
  3. 3. You want text that looks big but is not a section title. What should you do?

    Headings carry meaning. Use CSS for look and reserve heading elements for real section titles.
  4. 4. Which heading text is best?

    Specific, unique headings let users decide quickly from the headings list.

Summary

  • Many screen reader users navigate by headings, so they form a table of contents.
  • Use one h1, ordered levels without skips, and meaningful text.
  • Choose levels by structure; control appearance with CSS.
  • Review the assembled page outline when using components.

Next: Images and Text Alternatives