All rules

Sheath rule

seo-no-multiple-h1

Documents should have only one <h1> element.
Package
Core
Category
SEO
Default severity
warning by default
Auto-fix
Manual fix

#Why

The <h1> answers "what is this page about". Two of them means the page has two answers, and a screen reader user navigating by heading has no way to tell which one is the title and which is a section that was styled large.

#Examples

#Bad

<!-- Multiple h1 elements -->

<body>

    <h1>Welcome to Our Site</h1>

    <section>

        <h1>About Us</h1>  <!-- Should be h2 -->

        <p>Content here...</p>

    </section>

    <section>

        <h1>Our Services</h1>  <!-- Should be h2 -->

        <p>Content here...</p>

    </section>

</body>

#Good

<!-- Single h1 with proper heading hierarchy -->

<body>

    <h1>Welcome to Our Site</h1>

    <section>

        <h2>About Us</h2>

        <p>Content here...</p>

    </section>

    <section>

        <h2>Our Services</h2>

        <h3>Web Development</h3>

        <p>Content here...</p>

        <h3>Mobile Apps</h3>

        <p>Content here...</p>

    </section>

</body>

#Heading Hierarchy

<h1>Main Page Title</h1>           <!-- Only one -->

  <h2>Major Section</h2>           <!-- Multiple OK -->

    <h3>Subsection</h3>            <!-- Multiple OK -->

      <h4>Sub-subsection</h4>      <!-- Multiple OK -->

        <h5>Detail</h5>

          <h6>Minor detail</h6>

  <h2>Another Major Section</h2>

    <h3>Another Subsection</h3>

#Common Mistakes

Keep one primary page heading and use lower heading levels for sections.

Mistake Fix
Logo in <h1> + page title in <h1> Use CSS for logo, single <h1> for title
Each section has <h1> Use <h2> for section titles
Article title and site name both <h1> Article title as <h1>, site name in <header>

#Notes

  • The first <h1> is considered valid; subsequent ones are flagged
  • An <h1> inside a potentially repeating Blade loop is reported because the loop can render it more than once. The @empty arm of @forelse is not repeating
  • One <h1> per arm of a conditional (@if/@elseif/@else, @switch cases) still renders one <h1> per page and is accepted. Two inside the same arm, or one alongside an unconditional <h1>, are reported
  • This is an SEO recommendation; HTML5 technically allows multiple <h1> in sectioning content
  • Consider this alongside a11y-no-skip-heading-levels

#Related Rules