Page must contain one H1 heading
Description
This rule checks that every page contains at least one <h1> heading element. The <h1> heading represents the primary topic or purpose of the page and serves as the top-level heading in the document outline. Pages without an <h1> heading lack clear structural hierarchy, making it difficult for users, particularly those using assistive technologies, to quickly understand the main subject of the page and navigate its content efficiently.
Disabilities impacted
- Visual impairments: screen reader users rely on headings to navigate and understand page structure. The
<h1>heading is typically the first element announced when using heading navigation shortcuts. Without an<h1>, users cannot quickly identify the page’s main topic or orientation within the site. - Cognitive disabilities: users with cognitive disabilities benefit from clear, predictable document structures. An
<h1>heading provides an explicit, prominent label that communicates the page’s primary purpose, reducing cognitive load and improving comprehension. - Motor impairments: users who navigate via keyboard or voice commands often use heading shortcuts to jump directly to page content. The absence of an
<h1>heading removes a key navigation landmark, forcing users to navigate through more interactive elements to find the main content.
Why it matters
The <h1> heading is the most important heading on any web page. It communicates the page’s core topic, purpose, or function to all users. For assistive technology users, headings are a primary navigation method – they can call up a list of all headings on the page or jump directly between heading levels. Without an <h1>, the document outline lacks a clear root, making the entire heading structure ambiguous. Search engines also use <h1> headings to understand page content, affecting SEO. While HTML5 allows multiple <h1> elements when used with sectioning elements, having at least one <h1> on every page is a widely accepted best practice for accessibility and content clarity.
Coding problems and solutions
Common coding problems
- Missing H1 heading: the page contains no
<h1>element at all, often starting with an<h2>or other heading level. - H1 hidden or not visible: the
<h1>exists but is hidden using CSS (display: noneorvisibility: hidden), making it inaccessible to screen reader users as well. - Logo image without H1 text: using a logo image as the only heading without providing proper accessible text.
- Using H1 only for visual styling: an
<h1>is present but contains non-descriptive text like “Welcome” or “Home” that doesn’t communicate the page’s unique purpose. - Conditionally rendered H1: the
<h1>is added dynamically only under certain conditions (e.g., after user interaction), leaving the initial page load without an H1.
How to fix it
Add a descriptive H1 heading to every page
Ensure each page includes at least one <h1> element that clearly describes the main content or purpose of the page.
<!DOCTYPE html>
<html lang="en">
<head>
<title>Contact Us - Acme Company</title>
</head>
<body>
<h1>Contact Acme Company</h1>
<p>Reach out to our support team...</p>
</body>
</html><!-- No H1 heading at all -->
<!DOCTYPE html>
<html lang="en">
<head>
<title>Contact Us</title>
</head>
<body>
<h2>Contact Us</h2>
<p>Reach out to our support team...</p>
</body>
</html>Make H1 descriptive and unique
The <h1> should clearly indicate the page’s unique content, not just the site name or generic text.
<!-- Good: specific and descriptive -->
<h1>How to install a ceiling fan: a step-by-step guide</h1>
<!-- Good: unique page identifier -->
<h1>Edit your profile settings</h1>
<!-- Good: product or service page -->
<h1>Wireless noise-cancelling headphones - model X100</h1><!-- Too generic -->
<h1>Welcome</h1>
<!-- Only site name, no page context -->
<h1>Acme Company</h1>
<!-- Missing H1 entirely -->
<!-- (no h1 element on page) -->Ensure H1 is visible to all users
Do not hide the <h1> using CSS techniques that remove it from accessibility tree output. If visual design requires a different appearance, use CSS for styling, not for hiding.
<style>
.visually-hidden-h1 {
/* Style the H1 visibly, don't hide it */
font-size: 1.5rem;
color: #333;
margin: 1rem 0;
}
</style>
<h1 class="visually-hidden-h1">Contact Us</h1><!-- H1 is hidden from everyone -->
<h1 style="display: none;">Contact Us</h1>
<!-- H1 is visually hidden but still in DOM (screen reader accessible but not for sighted users -- still not ideal for most pages) -->
<h1 class="visually-hidden">Contact us</h1>Use logo with proper H1 when appropriate
If a logo serves as the page’s primary heading, ensure it is marked up as an <h1> with appropriate accessible text.
<h1>
<a href="/">
<img src="logo.svg" alt="Acme company - Home">
</a>
</h1>For single-page applications and dynamic content
In SPAs or pages with dynamic content, ensure an <h1> is always present after each view or state change. Update the <h1> content dynamically when the page context changes.
<!-- Static H1 container that gets updated -->
<h1 id="page-heading">Dashboard</h1>
<script>
// When navigating to a new "page" in an SPA
function updatePageHeading(newTitle) {
const heading = document.getElementById('page-heading');
if (heading) {
heading.textContent = newTitle;
} else {
// Fallback: create H1 if missing
const newH1 = document.createElement('h1');
newH1.id = 'page-heading';
newH1.textContent = newTitle;
document.body.insertBefore(newH1, document.body.firstElementChild);
}
}
// Example usage
updatePageHeading('Product details');
</script>Known Limitations
- Single-page applications (SPAs): this rule checks the DOM after initial page load. In SPAs that dynamically update content without full page reloads, the
<h1>might be missing on initial load but added later. Ensure your SPA framework adds an<h1>during the initial render. - Hidden H1 elements: the rule detects any
<h1>element present in the DOM, even if it is hidden via CSS. However, a hidden H1 (e.g.,display: none) does not provide a good user experience for sighted users and may still be considered problematic from a usability perspective. - Shadow DOM: this rule does not currently traverse Shadow DOM boundaries.
<h1>elements inside shadow roots may not be detected. - Iframes: each document (including iframes) should have its own
<h1>. This rule checks each document independently. - Multiple H1s: this rule only checks for presence of at least one
<h1>, not the correct number. While multiple<h1>elements are allowed in HTML5 when properly scoped with sectioning elements, having just one<h1>per page is still considered a best practice for accessibility. - Best practice rule: this is a best practices rule (not strictly required by WCAG), but having an
<h1>is strongly aligned with WCAG 1.3.1 (Info and Relationships) and WCAG 2.4.6 (Headings and Labels).
Resources
- W3C HTML Specification: The <h1> element
- MDN Web Docs: <h1>-<h6> heading elements
- WCAG 2.2 Understanding Success Criterion 1.3.1: Info and Relationships
- WCAG 2.2 Understanding Success Criterion 2.4.6: Headings and Labels
Rule
- Audit: Accessibility
- Standard: SiteLint Best Practices
- Level: Best Practice
- Success Criteria: N/A (Best Practice Rule)
- ID:
h1-must-be