Component

Heading

A text heading

A versatile heading tag component, including options for different heading levels and font sizes.

This is a h2 by default.

Real world examples:

Search for usage of this component on GitHub.

How it looks (preview) (preview all)

Download the full outcome

How to call this component

<%= render "govuk_publishing_components/components/heading", {
  text: "Download the full outcome"
} %>

Accessibility acceptance criteria

The heading must:

  • be part of a correct heading structure for a page
  • be semantically represented as a heading
  • convey the heading level

Other examples

Standard options

This component uses the component wrapper helper. It accepts the following options and applies them to the parent element of the component. See the component wrapper helper documentation for more detail.

  • id - accepts a string for the element ID attribute
  • data_attributes - accepts a hash of data attributes
  • aria - accepts a hash of aria attributes
  • classes - accepts a space separated string of classes, these should not be used for styling and must be prefixed with js-
  • margin_bottom - accepts a number from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale (defaults to no margin)
  • role - accepts a space separated string of roles
  • lang - accepts a language attribute value
  • open - accepts an open attribute value (true or false)
  • hidden - accepts an empty string, ‘hidden’, or ‘until-found’
  • tabindex - accepts an integer. The integer can also be passed as a string.
  • dir - accepts ‘rtl’, ‘ltr’, or ‘auto’.

Specific heading level (preview)

Original consultation 

<%= render "govuk_publishing_components/components/heading", {
  text: "Original consultation",
  heading_level: 3
} %>

Different font sizes (preview)

Set a different font size for the heading. Uses the GOV.UK Frontend heading sizes but defaults to 27px for legacy reasons. Valid options are xl, l, m and s.

This option is not tied to the heading_level option in order to give flexibility.

One big heading 

<%= render "govuk_publishing_components/components/heading", {
  text: "One big heading",
  font_size: "xl"
} %>

Right to left (preview)

مستندات 

<%= render "govuk_publishing_components/components/heading", {
  text: "مستندات"
} %>

With padding (preview)

Padded 

<%= render "govuk_publishing_components/components/heading", {
  text: "Padded",
  padding: true
} %>

With margin (preview)

The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale. It defaults to having no margin bottom.

Really big bottom margin 

<%= render "govuk_publishing_components/components/heading", {
  text: "Really big bottom margin",
  margin_bottom: 9
} %>

With border (preview)

A top border can be applied to the component of different thicknesses. Accepted values are 1 (1px), 2 (2px) and 5 (5px). Note that this works best with padding applied.

With a border 

<%= render "govuk_publishing_components/components/heading", {
  text: "With a border",
  padding: true,
  border_top: 2
} %>

With branding (preview)

Organisation colour branding can be added to the component as shown, if a top border is included.

Branding 

<%= render "govuk_publishing_components/components/heading", {
  text: "Branding",
  brand: "department-for-environment-food-rural-affairs",
  padding: true,
  border_top: 5
} %>

Inverted (preview)

On a dark background 

<%= render "govuk_publishing_components/components/heading", {
  text: "On a dark background",
  inverse: true
} %>

With lang attribute (preview)

The component is used on translated pages that don’t have a translation for the text strings. This means that it could display the fallback English string if the translate method can’t find an appropriate translation. This makes sure that the lang can be set to ensure that browsers understand which parts of the page are in each language.

The lang attribute must be set to a valid BCP47 string. A valid code can be the two or three letter language code - for example, English is en or eng, Korean is ko or kor - but if in doubt please check.

Ein gweinidogion 

<%= render "govuk_publishing_components/components/heading", {
  text: "Ein gweinidogion",
  lang: "cy"
} %>

With context (preview)

Context is applied sometimes where the heading is used as a page title H1. Note that the text size of the context is larger than the default size of the heading, so a larger font_size should be applied as shown.

Food opinion

I like toast 

<%= render "govuk_publishing_components/components/heading", {
  text: "I like toast",
  context: "Food opinion",
  font_size: "xl"
} %>

With context inside (preview)

If the context should be considered part of the page heading, you can nest the context within the <h1>.

Publication My page title 

<%= render "govuk_publishing_components/components/heading", {
  context: "Publication",
  text: "My page title",
  font_size: "xl",
  context_inside: true
} %>

With context language labelled (preview)

Sometimes this component appears on a page that has been translated. The title will naturally be supplied in the required language but the context string may fall back to the default. In these instances we need to label the language so the page remains semantic and screenreaders can handle the switch.

The lang attribute must be set to a valid BCP47 string. A valid code can be the two or three letter language code - for example, English is en or eng, Korean is ko or kor - but if in doubt please check.

Publication

My page title 

<%= render "govuk_publishing_components/components/heading", {
  context: "Publication",
  context_locale: "en",
  text: "My page title",
  font_size: "xl"
} %>

With context inverted (preview)

Publication

My page title 

<%= render "govuk_publishing_components/components/heading", {
  context: "Publication",
  text: "My page title",
  font_size: "xl",
  inverse: true
} %>