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 mobile top margin (preview)

On publications and consultations the layout of the page requires that the heading component have spacing above it on mobile. Since this is a specific use case, this is now an option on the component rather than the default behaviour.

It is intended that this option will ultimately be deprecated once more of the frontend is componentised and a general component model of margins is implemented.

Consultation description 

<%= render "govuk_publishing_components/components/heading", {
  text: "Consultation description",
  mobile_top_margin: true
} %>

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"
} %>