name: Heading
description: A text heading
body: |
  A versatile heading tag component, including options for different heading levels and font sizes.

  This is a `h2` by default.

  Real world examples:

  - [Publication](/government/publications/recognising-the-terrorist-threat)
  - [Consultation](/government/consultations/proposal-for-the-future-of-rotherham-goldthorpe-jobcentre)
accessibility_criteria: |
  The heading must:

  - be part of a correct heading structure for a page
  - be semantically represented as a heading
  - convey the heading level
uses_component_wrapper_helper: true  
examples:
  default:
    data:
      text: 'Download the full outcome'
  specific_heading_level:
    data:
      text: 'Original consultation'
      heading_level: 3
  different_font_sizes:
    description: |
      Set a different font size for the heading. Uses the [GOV.UK Frontend heading sizes](https://design-system.service.gov.uk/styles/typography/#headings) 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.
    data:
      text: 'One big heading'
      font_size: "xl"
  right_to_left:
    data:
      text: 'مستندات'
    context:
      right_to_left: true
  with_padding:
    description:
    data:
      text: 'Padded'
      padding: true
  with_margin:
    description: The component accepts a number for margin bottom from `0` to `9` (`0px` to `60px`) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). It defaults to having no margin bottom.
    data:
      text: 'Really big bottom margin'
      margin_bottom: 9
  with_mobile_top_margin:
    description: |
      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.
    data:
      text: 'Consultation description'
      mobile_top_margin: true
  with_border:
    description: 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.
    data:
      text: 'With a border'
      padding: true
      border_top: 2
  with_branding:
    description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) can be added to the component as shown, if a top border is included.
    data:
      text: 'Branding'
      brand: 'department-for-environment-food-rural-affairs'
      padding: true
      border_top: 5
  inverted:
    data:
      text: 'On a dark background'
      inverse: true
    context:
      dark_background: true
  with_lang_attribute:
    description: |
      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](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang#Language_tag_syntax). 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.
    data:
      text: "Ein gweinidogion"
      lang: "cy"