Component

List

A list - unordered or ordered, with or without counters / bullet points.

This is an ordered or unordered list, with or without visible bullets / numbers.

The items parameter can include HTML to display - such as links or another list. This HTML can either be directly coded or come from another component.

Search for usage of this component on GitHub.

How it looks (preview) (preview all)

Tony’s Chocolonely
Cherry Ripe
Snickers
Chomp
Penguin
Boost

How to call this component

<%= render "govuk_publishing_components/components/list", {
  items: [
    sanitize("Tony&rsquo;s Chocolonely"),
    sanitize("<a href=\"https://en.wikipedia.org/wiki/Cherry_Ripe_(chocolate_bar)\" rel=\"noopener\" class=\"govuk-link\">Cherry Ripe</a>"),
    "Snickers",
    "Chomp",
    "Penguin",
    "Boost"
  ]
} %>

GOV.UK Design System

This component incorporates components from the GOV.UK Design System:

List

Accessibility acceptance criteria

The 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 list may:

include an aria-label to contextualise the list if helpful

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’
type - accepts any valid type attribute e.g. ‘button’, ‘submit’, ‘text’
rel - accepts any valid rel attribute e.g. ‘nofollow’
target - accepts a valid target attribute e.g. ‘_blank’
title - accepts any string
draggable - accepts a draggable attribute value (“true” or “false”)

Unordered list with aria-label (preview)

A list with an aria-label

Tony’s Chocolonely
Cherry Ripe
Snickers
Chomp
Penguin
Boost

<%= render "govuk_publishing_components/components/list", {
  aria: {
    label: "A list of delicious chocolate bars."
  },
  items: [
    sanitize("Tony&rsquo;s Chocolonely"),
    sanitize("<a href=\"https://en.wikipedia.org/wiki/Cherry_Ripe_(chocolate_bar)\" rel=\"noopener\" class=\"govuk-link\">Cherry Ripe</a>"),
    "Snickers",
    "Chomp",
    "Penguin",
    "Boost"
  ]
} %>

Unordered list with bullet points (preview)

An unordered list with visible bullet points.

Tony’s Chocolonely
Cherry Ripe
Snickers
Chomp
Penguin
Boost

<%= render "govuk_publishing_components/components/list", {
  visible_counters: true,
  items: [
    sanitize("Tony&rsquo;s Chocolonely"),
    sanitize("<a href=\"https://en.wikipedia.org/wiki/Cherry_Ripe_(chocolate_bar)\" rel=\"noopener\" class=\"govuk-link\">Cherry Ripe</a>"),
    "Snickers",
    "Chomp",
    "Penguin",
    "Boost"
  ]
} %>

Ordered list without numbers (preview)

This is an ordered list where the numbers aren’t visible.

Tony’s Chocolonely
Cherry Ripe
Snickers
Chomp
Penguin
Boost

<%= render "govuk_publishing_components/components/list", {
  list_type: "number",
  items: [
    sanitize("Tony&rsquo;s Chocolonely"),
    sanitize("<a href=\"https://en.wikipedia.org/wiki/Cherry_Ripe_(chocolate_bar)\" rel=\"noopener\" class=\"govuk-link\">Cherry Ripe</a>"),
    "Snickers",
    "Chomp",
    "Penguin",
    "Boost"
  ]
} %>

Ordered list with numbers (preview)

This is an ordered list with the numbers visible.

Tony’s Chocolonely
Cherry Ripe
Snickers
Chomp
Penguin
Boost

<%= render "govuk_publishing_components/components/list", {
  list_type: "number",
  visible_counters: true,
  items: [
    sanitize("Tony&rsquo;s Chocolonely"),
    sanitize("<a href=\"https://en.wikipedia.org/wiki/Cherry_Ripe_(chocolate_bar)\" rel=\"noopener\" class=\"govuk-link\">Cherry Ripe</a>"),
    "Snickers",
    "Chomp",
    "Penguin",
    "Boost"
  ]
} %>

With extra spacing (preview)

Increases the amount of spacing between the list items.

Tony’s Chocolonely
Cherry Ripe
Snickers
Chomp
Penguin
Boost

<%= render "govuk_publishing_components/components/list", {
  extra_spacing: true,
  items: [
    sanitize("Tony&rsquo;s Chocolonely"),
    sanitize("<a href=\"https://en.wikipedia.org/wiki/Cherry_Ripe_(chocolate_bar)\" rel=\"noopener\" class=\"govuk-link\">Cherry Ripe</a>"),
    "Snickers",
    "Chomp",
    "Penguin",
    "Boost"
  ]
} %>

With id attribute (preview)

Sets the id on the ul or ol element.

Tony’s Chocolonely
Cherry Ripe
Snickers
Chomp
Penguin
Boost

<%= render "govuk_publishing_components/components/list", {
  id: "super-fantastic-chocolate-list",
  items: [
    sanitize("Tony&rsquo;s Chocolonely"),
    sanitize("<a href=\"https://en.wikipedia.org/wiki/Cherry_Ripe_(chocolate_bar)\" rel=\"noopener\" class=\"govuk-link\">Cherry Ripe</a>"),
    "Snickers",
    "Chomp",
    "Penguin",
    "Boost"
  ]
} %>

With margin (preview)

Sets the margin on the bottom of the list element.

The component accepts a number for margin bottom from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale. It defaults to having a 20px margin.

Tony’s Chocolonely
Cherry Ripe
Snickers
Chomp
Penguin
Boost

<%= render "govuk_publishing_components/components/list", {
  margin_bottom: 9,
  items: [
    sanitize("Tony&rsquo;s Chocolonely"),
    sanitize("<a href=\"https://en.wikipedia.org/wiki/Cherry_Ripe_(chocolate_bar)\" rel=\"noopener\" class=\"govuk-link\">Cherry Ripe</a>"),
    "Snickers",
    "Chomp",
    "Penguin",
    "Boost"
  ]
} %>