Component

Contents list

Provides a list of links with options for dashes or numbering.

Commonly used to lists a page’s contents 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 for details.

Search for usage of this component on GitHub.

How it looks (preview) (preview all)

How to call this component

<%= render "govuk_publishing_components/components/contents_list", {
  contents: [
    {
      href: "#first-thing",
      text: "First thing"
    },
    {
      href: "#second-thing",
      text: "Second thing"
    },
    {
      href: "#third-thing",
      text: "Third thing"
    }
  ]
} %>

Accessibility acceptance criteria

The component must be a landmark with a navigation role.

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”.

Links in the component must:

• accept focus
• be focusable with a keyboard
• be usable with a keyboard
• indicate when they have focus
• change in appearance when touched (in the touch-down state)
• change in appearance when hovered
• be usable with touch
• be usable with voice commands
• have visible text
• have meaningful text

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-
• role - accepts a space separated string of roles
• lang - accepts a language attribute value
• open - accepts an open attribute value (true or false)

Underline links (preview)

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.

<%= render "govuk_publishing_components/components/contents_list", {
  underline_links: true,
  contents: [
    {
      href: "#first-thing",
      text: "Lorem &amp; ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
    },
    {
      href: "#second-thing",
      text: sanitize("Ut enim &mdash; 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 (preview)

<%= render "govuk_publishing_components/components/contents_list", {
  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 (preview)

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.

<%= render "govuk_publishing_components/components/contents_list", {
  contents: [
    {
      href: "#first-thing",
      text: "First"
    },
    {
      href: "#two",
      text: "Second",
      active: true
    },
    {
      href: "#third-thing",
      text: "Third thing"
    }
  ]
} %>

Nested contents lists (preview)

<%= render "govuk_publishing_components/components/contents_list", {
  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 (preview)

<%= render "govuk_publishing_components/components/contents_list", {
  format_numbers: true,
  contents: [
    {
      href: "#first-thing",
      text: "1.&nbsp;First thing"
    },
    {
      href: "#two",
      active: true,
      text: "2. Second thing"
    },
    {
      href: "#third-thing",
      text: "3. Third &amp;thing"
    }
  ]
} %>

Formats complex numbers (preview)

<%= render "govuk_publishing_components/components/contents_list", {
  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 (preview)

<%= render "govuk_publishing_components/components/contents_list", {
  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 (preview)

<%= render "govuk_publishing_components/components/contents_list", {
  contents: [
    {
      href: "#section",
      text: "هل يمكنك تقديم"
    },
    {
      href: "#section-1",
      text: "أعد مستند"
    },
    {
      href: "#section-2",
      text: "تقديم الطلب"
    }
  ]
} %>

Right to left with formatted numbers (preview)

<%= render "govuk_publishing_components/components/contents_list", {
  format_numbers: true,
  contents: [
    {
      href: "#section",
      text: "هل يمكنك تقديم"
    },
    {
      href: "#section-1",
      text: "أعد مستند"
    },
    {
      href: "#section-2",
      text: "تقديم الطلب"
    }
  ]
} %>

Right to left with nested contents lists (preview)

<%= render "govuk_publishing_components/components/contents_list", {
  contents: [
    {
      href: "#section",
      text: "هل يمكنك تقديم"
    },
    {
      href: "#section-1",
      text: "أعد مستند"
    },
    {
      href: "#section-2",
      text: "تقديم الطلب",
      items: [
        {
          href: "#section",
          text: "هل يمكنك تقديم"
        },
        {
          href: "#section-1",
          text: "أعد مستند"
        },
        {
          href: "#section-2",
          text: "تقديم الطلب"
        }
      ]
    }
  ]
} %>

With branding (preview)

Where this component could be used on an organisation page (such as the Attorney General’s Office) branding can be applied for link colours and border colours. See the branding documentation for more details.

<%= render "govuk_publishing_components/components/contents_list", {
  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"
        }
      ]
    }
  ]
} %>

Without ga4 tracking (preview)

Disables GA4 link tracking on the list. Tracking is enabled by default.

<%= render "govuk_publishing_components/components/contents_list", {
  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"
        }
      ]
    }
  ]
} %>