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
examples:
  default:
    data:
      text: 'Download the full outcome'
  specific_heading_level:
    data:
      text: 'Original consultation'
      heading_level: 3
  different_font_sizes:
    description: Choose a different font size. Valid options are 24 (24px) and 19 (19px), with the component defaulting to 27px, appropriate for a H1. This option is not tied to the heading_level option in order to give flexibility.
    data:
      text: 'Heading 3'
      font_size: 19
  with_id_attribute:
    data:
      text: 'Detail of outcome'
      id: 'detail_of_outcome'
  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](http://govuk-frontend-review.herokuapp.com/docs/#settings/spacing-variable-govuk-spacing-points). 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/master/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