Component

Contents list

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

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 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-
• margin_bottom - accepts a number from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale (defaults to no margin)
• role - accepts a space separated string of roles
• lang - accepts a language attribute value
• open - accepts an open attribute value (true or false)
• hidden - accepts an empty string, ‘hidden’, or ‘until-found’
• tabindex - accepts an integer. The integer can also be passed as a string.
• dir - accepts ‘rtl’, ‘ltr’, or ‘auto’.

With bottom margin (preview)

The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale. The default margin bottom is 20px (govuk-spacing(4)).

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

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 number 10 branding (preview)

Organisation colour branding can be added to the component as shown.

<%= render "govuk_publishing_components/components/contents_list", {
  brand: "prime-ministers-office-10-downing-street",
  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 (preview)

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.

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

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.

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