Heading with subheadingStatusdevelopment

Markup for use when displaying a heading with a subheading or tagline.

Guidance

Often there is a requirement for a page or a component to contain a subheading or a tagline immediately below the main header of the element. Visually this may look like a secondary heading such as an h2 or h3, but semantically this text is rarely ever useful as a heading for sectioning content

This content should be rendered as standard page paragraphs, but with additional markup to indicate to browsers and screenreaders what the meaning of this content is and how it connects to the heading.

At the time of writing, support of the role="doc-subtitle" attribute is patchy and implementations contain bugs that make it detrimental to the legibility of the page on some screenreaders (See references below). For now, the recommendation is to use the <hgroup> tag alone.

Example page hero

Open in a new tab

<section class="hero"><hgroup><h1 class="hero__title">Lorem ipsum dolor sit amet</h1><p class="hero__subtitle">Mauris consectetur varius ullamcorper. Aliquam erat volutpat.</p></hgroup><div class="hero__body push-top"><a href="#" class="btn" aria-label="Read more about Lorem ipsum dolor sit amet">Read more</a></div></section>

Example card

Open in a new tab

<article class="card"><hgroup class="card__header"><h2 class="card__title">Lorem ipsum dolor sit amet</h2><p class="card__subtitle">Mauris consectetur varius ullamcorper. Aliquam erat volutpat.</p></hgroup><div class="card__body"><p>Cras quis posuere sem. Phasellus sit amet convallis tellus, a sollicitudin nulla. Mauris aliquam felis ac nunc tempor, non vehicula ipsum congue. Vestibulum quis consectetur leo. Vestibulum tincidunt vestibulum turpis quis facilisis. Ut viverra est mi. Nullam ac tincidunt orci. Donec at imperdiet neque.</p><a href="#" class="btn card__btn" aria-label="Read more about Lorem ipsum dolor sit amet">Read more</a></div></article>

Acceptance criteria

The following is a list of example acceptance criteria to test against when using this pattern. These critera should test that the specific markup requirements are met, and that the search behaves visually and functionally as expected.

For validation in developer tools / web inspector

Any headings followed by a tagline or immediate subtitle should be wrapped in an
```
<hgroup>
```
tag
Any taglines or subtitles should be
```
<p>
```
tag
The level of the heading within the
```
<hgroup>
```
tag will depend on the surrounding page context, and should follow the page heirarchy
The
```
<hgroup>
```
must follow HTML5 validation rules and contain only one heading tag with one or more supporting paragraphs

For visual validation

The heading and subtitle should give a visual indication of content heirarchy

For functional validation

The subtitle should not appear as a heading within the accessibility tree, and should not be announced as such

UI Patterns