Page heading

This pattern is the main heading of the current page, which lets the user know what information is being asked for or provided.

When to use

Use a page heading on every page.

You can also include a section heading if it helps the user know where they are in a service. For example, in long services and those with more than one section.

How it works

You need HMRC Frontend to use this pattern — find out how to install HMRC Frontend. If you use the HMRC Nunjucks macro, you must copy and paste the entire macro into your code.

Every page must have a main heading coded as an <h1>.

Open this example in a new tab Display in English Display in Welsh

HTML
Nunjucks

              <header class="hmrc-page-heading">
  <h1 class="govuk-heading-l">What is your name?</h1>
</header>

                <header class="hmrc-page-heading">
  <h1 class="govuk-heading-l">Beth yw’ch enw?</h1>
</header>

                {% from "hmrc/components/page-heading/macro.njk"  import hmrcPageHeading %}

{{ hmrcPageHeading({
  text: "What is your name?",
  headingClasses: "govuk-heading-l"
}) }}

                  {% from "hmrc/components/page-heading/macro.njk"  import hmrcPageHeading %}

{{ hmrcPageHeading({
  text: "Beth yw’ch enw?",
  headingClasses: "govuk-heading-l"
}) }}

For accessibility reasons, if you use a section heading, it should be coded as a paragraph <p> inside a <header>.

Open this example in a new tab Display in English Display in Welsh

HTML
Nunjucks

              <header class="hmrc-page-heading">
  <h1 class="govuk-heading-l">What is your name?</h1>
  <p class="hmrc-caption govuk-caption-xl"><span class="govuk-visually-hidden">This section is </span>Personal details</p>
</header>

                <header class="hmrc-page-heading">
  <h1 class="govuk-heading-l">Beth yw’ch enw?</h1>
  <p class="hmrc-caption govuk-caption-xl"><span class="govuk-visually-hidden">This section is </span>Manylion personol</p>
</header>

                {% from "hmrc/components/page-heading/macro.njk"  import hmrcPageHeading %}

{{ hmrcPageHeading({
  text: "What is your name?",
  section: "Personal details",
  headingClasses: "govuk-heading-l"
}) }}

                  {% from "hmrc/components/page-heading/macro.njk"  import hmrcPageHeading %}

{{ hmrcPageHeading({
  text: "Beth yw’ch enw?",
  section: "Manylion personol",
  headingClasses: "govuk-heading-l"
}) }}

This makes sure that when using screen readers and other assistive technologies, the page heading and the section heading are:

separate
in the correct source order
displayed the correct way
read out the correct way

Change or remove any visually hidden content to meet your users’ needs.

Research

The recommended code has been tested with screen reader users and all browsers, devices and assistive technologies. Research showed it:

displayed as expected
worked consistently across different assistive technologies
helped users know where they were in the service
did not distract users from their task

We need more research. If you have used the page heading and section heading, get in touch to share your research findings.

Discuss the page heading on GitHub