1. Government Frontend Component Guide
  2. Contents list

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

The contents list may: - include an aria-label to contextualise the list if helpful

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

Other examples

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 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 (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"
    }
  ]
} %>

Aria label (preview)

An aria-label string can be used to contextualise the navigation for assistive technology.

<%= render "govuk_publishing_components/components/contents_list", {
  aria_label: "Pages in this guide",
  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. First thing"
    },
    {
      href: "#two",
      active: true,
      text: "2. Second thing"
    },
    {
      href: "#third-thing",
      text: "3. Third 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 a title (preview)

The component can be used to provide a list of links to other pages, in which case the ‘Contents’ title is inappropriate and can be removed.

<%= render "govuk_publishing_components/components/contents_list", {
  hide_title: true,
  contents: [
    {
      href: "#first-thing",
      text: "Community best practice",
      items: [
        {
          href: "#second-thing",
          text: "Guidance and regulation"
        },
        {
          href: "#third-thing",
          text: "Consultations"
        }
      ]
    }
  ]
} %>

With different font size (preview)

Choose a different font size. Valid options are 24 (24px) and 19 (19px), with the component defaulting to 16px.

<%= render "govuk_publishing_components/components/contents_list", {
  font_size: 24,
  contents: [
    {
      href: "#first-thing",
      text: "Community best practice"
    },
    {
      href: "#second-thing",
      text: "Guidance and regulation"
    },
    {
      href: "#third-thing",
      text: "Consultations"
    }
  ]
} %>