Using HMRC section headings with GOVUK Frontend components

readme.md

Because there is no way of maintaining the HMRC page heading pattern and incorporating it with the current Gov Frontend components (or using aria to reference an external section heading), I’ve been recommending that services send the whole construct (without using the header element due to permitted nesting rules) through to the legend or label.

It isn’t ideal but is better than having repeated content or missing the section heading. As the section heading is announced after the label then the important information is still front-loaded.

Labels

For example, construct a variable to contain the html for the heading and the caption

@headingSnippetLabel = @{"Heading copy <span class='govuk-caption-xl hmrc-caption-xl'><span class='govuk-visually-hidden'>This section is: </span>Caption copy</span>"}

and send this through to the component as the label

label = Label(
  isPageHeading = true,
  classes = "govuk-label--l hmrc-page-heading govuk-!-margin-top-0 govuk-!-margin-bottom-2",
  content = HtmlContent(headingSnippetLabel)
)

This produces

<h1 class="govuk-label-wrapper">
    <label class="govuk-label govuk-label--l hmrc-page-heading govuk-!-margin-top-0 govuk-!-margin-bottom-2" for="the-thing">
      Heading copy <span class="govuk-caption-xl hmrc-caption-xl"><span class="govuk-visually-hidden">This section is: </span>Caption copy</span>
    </label>
</h1>

Legends

Legends are a bit different because it wraps the h1 and caption. Because you can't send classes direct to the h1 you have to add the h1 to the content itself.

@headingSnippet = @{"<h1 class='govuk-fieldset__heading hmrc-page-heading govuk-!-margin-top-0 govuk-!-margin-bottom-0'>Heading copy<span class='govuk-caption-xl hmrc-caption-xl'><span class='govuk-visually-hidden'>This section is: </span>Caption copy</span></h1>"}

and

legend = Some(Legend(
    content = HtmlContent(headingSnippet),
    classes = "govuk-fieldset__legend--l",
    isPageHeading = false
))

produces

<legend class="govuk-fieldset__legend govuk-fieldset__legend--l">
  <h1 class="govuk-fieldset__heading hmrc-page-heading govuk-!-margin-top-0 govuk-!-margin-bottom-0">
    Heading copy
    <span class="govuk-caption-xl hmrc-caption-xl"><span class="govuk-visually-hidden">This section is: </span>Caption copy</span>
  </h1>
</legend>