name: Contents list
description: Provides a list of links with options for dashes or numbering.
body: |
  Commonly used to list the contents of a page with links pointing to headings within the document, but can also be used for a list of links to other pages.

  Pass a list of contents each with an `href` and `text`. The `href` can point at the ID of a heading within the page.

  Supports nesting contents one level deep, currently only used by specialist documents. When nesting the top level list items display in bold.

  `format_numbers` option will pull out numbers in the link text to render them as though they were the list style type. Applies to numbers at the start of text, with or without a decimal. See the [format complex numbers fixture](/component-guide/contents-list/formats_complex_numbers) for details.
accessibility_criteria: |
  The component must be [a landmark with a navigation role](https://accessibility.blog.gov.uk/2016/05/27/using-navigation-landmarks/).

  The contents list must:

  - inform the user how many items are in the list
  - convey the content structure
  - indicate the current page when contents span different pages, and not link to itself
  - include an aria-label to contextualise the list
  - ensure dashes before each list item are hidden from screen readers

  Links with formatted numbers must separate the number and text with a space for correct screen reader pronunciation. This changes pronunciation from "1 dot Item" to "1 Item".
shared_accessibility_criteria:
  - link
accessibility_excluded_rules:
  - skip-link # The examples for this component are using references to sections on the page that do not exist in examples
uses_component_wrapper_helper: true
examples:
  default:
    data:
      contents:
        - href: "#first-thing"
          text: First thing
        - href: "#second-thing"
          text: Second thing
        - href: "#third-thing"
          text: Third thing
  with_bottom_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). The default margin bottom is `20px` (`govuk-spacing(4)`).
    data:
      margin_bottom: 9
      contents:
        - href: "#first-thing"
          text: First thing
        - href: "#second-thing"
          text: Second thing
        - href: "#third-thing"
          text: Third thing
  underline_links:
    description: By default we do not underline links in this component even though this is the general approach on GOV.UK. This is because some of the examples below (particularly those with numbers) do not work well with underlined links. Instead, this option allows the links to be underlined where appropriate.
    data:
      underline_links: true
      contents:
        - href: "#first-thing"
          text: Lorem & ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
        - href: "#second-thing"
          text: Ut enim — ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
        - href: "#third-thing"
          text: Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
  long_text:
    data:
      contents:
        - href: "#first-thing"
          text: Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
        - href: "#second-thing"
          text: Another pretty long contents list entry, not as long as the first, but still a little.
        - href: "#third-thing"
          text: Third thing
  active_content_link:
    description: 'An active state allows for "you are here" items in a contents list that spans different pages to avoid linking back to the current page.'
    data:
      contents:
        - href: "#first-thing"
          text: First
        - href: "#two"
          text: Second
          active: true
        - href: "#third-thing"
          text: Third thing
  nested_contents_lists:
    data:
      contents:
        - href: "#first-thing"
          text: First thing
        - href: "#second-thing"
          text: Second thing
        - href: "#third-thing"
          text: Third thing
          items:
            - href: "#sub-third-thing"
              text: Sub third thing
            - href: "#another-third-thing"
              text: Another third thing
        - href: "#fourth-thing"
          text: Fourth thing
  formats_numbers:
    data:
      format_numbers: true
      contents:
        - href: "#first-thing"
          text: 1. First thing
        - href: "#two"
          active: true
          text: 2. Second thing
        - href: "#third-thing"
          text: 3. Third &thing
  formats_complex_numbers:
    data:
      format_numbers: true
      contents:
        - href: "#"
          text: 1. Item
        - href: "#"
          text: 1.1 Sub item
        - href: "#"
          text: 1.2 Sub item
        - href: "#"
          text: "1.02 longer decimals allowed"
        - href: "#"
          text: "1.021 even longer decimals ignored"
        - href: "#"
          text: 1 Number without period
        - href: "#"
          text: 10. Two digit numbers
        - href: "#"
          text: 99. Two digit numbers
        - href: "#"
          text: 100. Three digit numbers
        - href: "#"
          text: 2017 four digit numbers ignored
        - href: "#"
          text: "2001: A space odyssey"
  nested_with_formatted_numbers:
    data:
      format_numbers: true
      contents:
        - href: "#first-thing"
          text: 1. First thing
          items:
          - href: "#second-thing"
            text: 2. Numbers not parsed
          - href: "#third-thing"
            text: 3. Numbers are just text
        - href: "#first-thing"
          text: 2. Next thing
          items:
          - href: "#second-thing"
            text: No numbers here
          - href: "#third-thing"
            active: true
            text: None here either
  right_to_left:
    data:
      contents:
        - href: "#section"
          text: "هل يمكنك تقديم"
        - href: "#section-1"
          text: "أعد مستند"
        - href: "#section-2"
          text: "تقديم الطلب"
    context:
      right_to_left: true
  right_to_left_with_formatted_numbers:
    data:
      format_numbers: true
      contents:
        - href: "#section"
          text: "هل يمكنك تقديم"
        - href: "#section-1"
          text: "أعد مستند"
        - href: "#section-2"
          text: "تقديم الطلب"
    context:
      right_to_left: true
  right_to_left_with_nested_contents_lists:
    data:
      contents:
        - href: "#section"
          text: "هل يمكنك تقديم"
        - href: "#section-1"
          text: "أعد مستند"
        - href: "#section-2"
          text: "تقديم الطلب"
          items:
            - href: "#section"
              text: "هل يمكنك تقديم"
            - href: "#section-1"
              text: "أعد مستند"
            - href: "#section-2"
              text: "تقديم الطلب"
    context:
      right_to_left: true
  with_branding:
    description: Where this component could be used on an organisation page (such as the [Attorney General's Office](https://www.gov.uk/government/organisations/attorney-generals-office)) branding can be applied for link colours and border colours. See the [branding documentation](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) for more details.
    data:
      brand: 'department-for-environment-food-rural-affairs'
      format_numbers: true
      contents:
        - href: "#first-thing"
          text: 1. First thing
          items:
          - href: "#second-thing"
            text: 2. Numbers not parsed
          - href: "#third-thing"
            text: 3. Numbers are just text
  with_alternative_line_style:
    description: With this option, the individual lines get different styling. The left hand indent and dashes are removed, there's more vertical space between each list item and the active links are styled with a vertical left hand border.
    data:
      alternative_line_style: true
      contents:
        - href: "#first-thing"
          text: First page title link
        - href: "#second-thing"
          text: Second page title link
        - href: "#third-thing"
          text: Third page title link
          active: true
        - href: "#fourth-thing"
          text: Fourth page title link
        - href: "#fifth-thing"
          text: Fifth page title link
  with_custom_title:
    description: With this option, the 'Contents' title is replaced with the supplied alternate title. This should only be used when using this component as a navigation element on landing pages. Typically used with `alternative_line_style`.
    data:
      title: "An alternate title"
      contents:
        - href: "#first-thing"
          text: First page title link
        - href: "#second-thing"
          text: Second page title link
        - href: "#third-thing"
          text: Third page title link
          active: true
        - href: "#fourth-thing"
          text: Fourth page title link
        - href: "#fifth-thing"
          text: Fifth page title link
  without_ga4_tracking:
    description: Disables GA4 link tracking on the list. Tracking is enabled by default.
    data:
      disable_ga4: true
      contents:
        - href: "https://www.gov.uk"
          text: 1. First thing
          items:
          - href: "#second-thing"
            text: 1. Nested Item
          - text: 2. Nested Item
            active: true
        - href: "#first-thing"
          text: 2. Second thing
          items:
          - href: "#second-thing"
            text: 1. Nested Item
          - href: "https://www.gov.uk/browse"
            text: 2. Nested Item