name: Page title
description: A page title with optional context label
body: |
  This contains an optional parameter for average title length. The two valid
  values for this parameter are 'medium' or 'long'. Medium titles are titles
  where the average is around 30 characters or less. Long titles would have
  an average length of nearer 50 characters or more.

  On average the titles on government bits of content are 50 characters. The
  average for bits of general guidance are nearer 27 characters long.
accessibility_criteria: |
  The page title must:

  - be part of a correct heading structure for a page
  - be semantically represented as a heading
  - convey the heading level
shared_accessibility_criteria:
  - link
examples:
  default:
    data:
      title: My page title
  with_context:
    data:
      context: Publication
      title: My page title
  with_context_inside:
    description: |
      If the context should be considered part of the page heading, you can nest the context within the <code><h1></code>.
    data:
      context: Publication
      title: My page title
      context_inside: true
  with_context_language_labelled:
    description: |
      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](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:
      context: Publication
      context_locale: en
      title: My page title
  long_title_with_context:
    data:
      context: Publication
      title: My page title which is often really long and verbose and has lots of extra words it doesn't need
      average_title_length: long
  with_margin_bottom:
    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 a margin bottom of 50px.

      This margin is responsive at certain sizes, see the link above for more detail. Note also that the component has a (responsive) top margin set as well, which cannot be modified.
    data:
      title: 'Margin bottom of 10px'
      margin_bottom: 2
  in_html_publication:
    description: Page titles are used in HTML Publications ([see example](https://www.gov.uk/government/publications/fees-for-civil-and-family-courts/court-fees-for-the-high-court-county-court-and-family-court))
    data:
      context: Publication
      title: HTML publication page title
      inverse: true
      margin_bottom: 0
    context:
      dark_background: true