Content presentation - Summary list

Use the summary list to summarise information, for example, a user’s responses at the end of a form.

Open this default summary list example in new window
Copy default summary list code 
<dl class="hs2-summary-list">

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Name
    </dt>
    <dd class="hs2-summary-list__value">
      Tom Smith
    </dd>

    <dd class="hs2-summary-list__actions">

      <a href="#">
        Change<span class="hs2-u-visually-hidden"> name</span>
      </a>

    </dd>

  </div>

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Date of birth
    </dt>
    <dd class="hs2-summary-list__value">
      26 June 1990
    </dd>

    <dd class="hs2-summary-list__actions">

      <a href="#">
        Change<span class="hs2-u-visually-hidden"> date of birth</span>
      </a>

    </dd>

  </div>

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Contact information
    </dt>
    <dd class="hs2-summary-list__value">
      2 Snow Hill<br>Birmingham<br> B4 6GA
    </dd>

    <dd class="hs2-summary-list__actions">

      <a href="#">
        Change<span class="hs2-u-visually-hidden"> contact information</span>
      </a>

    </dd>

  </div>

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Contact details
    </dt>
    <dd class="hs2-summary-list__value">
      <p>07123 456789</p>
      <p>tom.smith@example.com</p>
    </dd>

    <dd class="hs2-summary-list__actions">

      <a href="#">
        Change<span class="hs2-u-visually-hidden"> contact details</span>
      </a>

    </dd>

  </div>

</dl>
Close default summary list code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for default summary list
Name Type Required Description
Name rows Type array Required true Description Array of row item objects.
Name rows[].classes Type string Required false Description Classes to add to the row `div`.
Name rows[].key.text Type string Required true Description If `html` is set, this is not required. Text to use within the each key. If `html` is provided, the `text` argument will be ignored.
Name rows[].key.html Type string Required true Description
Name rows[].key.classes Type string Required false Description Classes to add to the key wrapper.
Name rows[].value.text Type string Required true Description If `html` is set, this is not required. Text to use within the each value. If `html` is provided, the `text` argument will be ignored.
Name rows[].value.html Type string Required true Description If `text` is set, this is not required. HTML to use within the each value. If `html` is provided, the `text` argument will be ignored.
Name rows[].value.classes Type string Required false Description Classes to add to the value wrapper.
Name rows[].actions.classes Type string Required false Description Classes to add to the actions wrapper.
Name rows[].actions.items Type array Required false Description Array of action item objects.
Name actions.items[].href Type string Required true Description The value of the link href attribute for an action item.
Name actions.items[].text Type string Required true Description If `html` is set, this is not required. Text to use within each action item. If `html` is provided, the `text` argument will be ignored.
Name actions.items[].html Type string Required true Description If `text` is set, this is not required. HTML to use within the each action item. If `html` is provided, the `text` argument will be ignored.
Name actions.items[].visuallyHiddenText Type string Required false Description Actions rely on context from the surrounding content so may require additional accessible text, text supplied to this option is appended to the end, use `html` for more complicated scenarios.
Name classes Type string Required false Description Classes to add to the summary list container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the summary list container.
Copy default summary list code 
{% from "summary-list/macro.njk" import summaryList %}

{{ summaryList({
  rows: [
    {
      key: {
        text: "Name"
      },
      value: {
        text: "Tom Smith"
      },
      actions: {
        items: [
          {
            href: "#",
            text: "Change",
            visuallyHiddenText: "name"
          }
        ]
      }
    },
    {
      key: {
        text: "Date of birth"
      },
      value: {
        text: "26 June 1990"
      },
      actions: {
        items: [
          {
            href: "#",
            text: "Change",
            visuallyHiddenText: "date of birth"
          }
        ]
      }
    },
    {
      key: {
        text: "Contact information"
      },
      value: {
        html: "2 Snow Hill<br>Birmingham<br> B4 6GA"
      },
      actions: {
        items: [
          {
            href: "#",
            text: "Change",
            visuallyHiddenText: "contact information"
          }
        ]
      }
    },
    {
      key: {
        text: "Contact details"
      },
      value: {
        html: '<p>07123 456789</p><p>tom.smith@example.com</p>'
      },
      actions: {
        items: [
          {
            href: "#",
            text: "Change",
            visuallyHiddenText: "contact details"
          }
        ]
      }
    }
  ]
}) }}
Close default summary list code

When to use summary lists

Use the summary list component to present pairs of related information, known as key-value pairs, in a list, where:

  • the key is a label, like "Name"
  • the value is the piece of information itself, like "John Smith"

Think about how you can use the summary list along with other components or patterns to give users a sense of control. You can use it to summarise a user’s responses at the end of a form, for example as part of the GOV.UK check answers pattern.

When not to use summary lists

The summary list uses the description list <dl> HTML element, so only use it to present information that has a key and at least 1 value.

Do not use it for tabular data or a simple list of information or tasks, like a task list page. (See the GOV.UK task list page pattern.) For those, use a <table>, <ul> or <ol>.

How to use summary lists

There are 2 ways to use the summary list component. You can use HTML or, if you’re using Nunjucks or the HS2.UK prototype kit, you can use the Nunjucks macro.

Open this default summary list example in new window
Copy default summary list code 
<dl class="hs2-summary-list">

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Name
    </dt>
    <dd class="hs2-summary-list__value">
      Tom Smith
    </dd>

    <dd class="hs2-summary-list__actions">

      <a href="#">
        Change<span class="hs2-u-visually-hidden"> name</span>
      </a>

    </dd>

  </div>

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Date of birth
    </dt>
    <dd class="hs2-summary-list__value">
      26 June 1990
    </dd>

    <dd class="hs2-summary-list__actions">

      <a href="#">
        Change<span class="hs2-u-visually-hidden"> date of birth</span>
      </a>

    </dd>

  </div>

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Contact information
    </dt>
    <dd class="hs2-summary-list__value">
      2 Snow Hill<br>Birmingham<br> B4 6GA
    </dd>

    <dd class="hs2-summary-list__actions">

      <a href="#">
        Change<span class="hs2-u-visually-hidden"> contact information</span>
      </a>

    </dd>

  </div>

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Contact details
    </dt>
    <dd class="hs2-summary-list__value">
      <p>07123 456789</p>
      <p>tom.smith@example.com</p>
    </dd>

    <dd class="hs2-summary-list__actions">

      <a href="#">
        Change<span class="hs2-u-visually-hidden"> contact details</span>
      </a>

    </dd>

  </div>

</dl>
Close default summary list code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for default summary list
Name Type Required Description
Name rows Type array Required true Description Array of row item objects.
Name rows[].classes Type string Required false Description Classes to add to the row `div`.
Name rows[].key.text Type string Required true Description If `html` is set, this is not required. Text to use within the each key. If `html` is provided, the `text` argument will be ignored.
Name rows[].key.html Type string Required true Description
Name rows[].key.classes Type string Required false Description Classes to add to the key wrapper.
Name rows[].value.text Type string Required true Description If `html` is set, this is not required. Text to use within the each value. If `html` is provided, the `text` argument will be ignored.
Name rows[].value.html Type string Required true Description If `text` is set, this is not required. HTML to use within the each value. If `html` is provided, the `text` argument will be ignored.
Name rows[].value.classes Type string Required false Description Classes to add to the value wrapper.
Name rows[].actions.classes Type string Required false Description Classes to add to the actions wrapper.
Name rows[].actions.items Type array Required false Description Array of action item objects.
Name actions.items[].href Type string Required true Description The value of the link href attribute for an action item.
Name actions.items[].text Type string Required true Description If `html` is set, this is not required. Text to use within each action item. If `html` is provided, the `text` argument will be ignored.
Name actions.items[].html Type string Required true Description If `text` is set, this is not required. HTML to use within the each action item. If `html` is provided, the `text` argument will be ignored.
Name actions.items[].visuallyHiddenText Type string Required false Description Actions rely on context from the surrounding content so may require additional accessible text, text supplied to this option is appended to the end, use `html` for more complicated scenarios.
Name classes Type string Required false Description Classes to add to the summary list container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the summary list container.
Copy default summary list code 
{% from "summary-list/macro.njk" import summaryList %}

{{ summaryList({
  rows: [
    {
      key: {
        text: "Name"
      },
      value: {
        text: "Tom Smith"
      },
      actions: {
        items: [
          {
            href: "#",
            text: "Change",
            visuallyHiddenText: "name"
          }
        ]
      }
    },
    {
      key: {
        text: "Date of birth"
      },
      value: {
        text: "26 June 1990"
      },
      actions: {
        items: [
          {
            href: "#",
            text: "Change",
            visuallyHiddenText: "date of birth"
          }
        ]
      }
    },
    {
      key: {
        text: "Contact information"
      },
      value: {
        html: "2 Snow Hill<br>Birmingham<br> B4 6GA"
      },
      actions: {
        items: [
          {
            href: "#",
            text: "Change",
            visuallyHiddenText: "contact information"
          }
        ]
      }
    },
    {
      key: {
        text: "Contact details"
      },
      value: {
        html: '<p>07123 456789</p><p>tom.smith@example.com</p>'
      },
      actions: {
        items: [
          {
            href: "#",
            text: "Change",
            visuallyHiddenText: "contact details"
          }
        ]
      }
    }
  ]
}) }}
Close default summary list code

Summary list with actions

You can add actions to a summary list, like a "Change" link to let users go back and edit their answer.

People who use assistive technology, like a screen reader, may hear the action links out of context and not know what they do. To give more context, add visually hidden text to the links. This means a screen reader user will hear a meaningful action, like "Change name" or "Change date of birth".

Open this default summary list example in new window
Copy default summary list code 
<dl class="hs2-summary-list">

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Name
    </dt>
    <dd class="hs2-summary-list__value">
      Tom Smith
    </dd>

    <dd class="hs2-summary-list__actions">

      <a href="#">
        Change<span class="hs2-u-visually-hidden"> name</span>
      </a>

    </dd>

  </div>

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Date of birth
    </dt>
    <dd class="hs2-summary-list__value">
      26 June 1990
    </dd>

    <dd class="hs2-summary-list__actions">

      <a href="#">
        Change<span class="hs2-u-visually-hidden"> date of birth</span>
      </a>

    </dd>

  </div>

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Contact information
    </dt>
    <dd class="hs2-summary-list__value">
      2 Snow Hill<br>Birmingham<br> B4 6GA
    </dd>

    <dd class="hs2-summary-list__actions">

      <a href="#">
        Change<span class="hs2-u-visually-hidden"> contact information</span>
      </a>

    </dd>

  </div>

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Contact details
    </dt>
    <dd class="hs2-summary-list__value">
      <p>07123 456789</p>
      <p>tom.smith@example.com</p>
    </dd>

    <dd class="hs2-summary-list__actions">

      <a href="#">
        Change<span class="hs2-u-visually-hidden"> contact details</span>
      </a>

    </dd>

  </div>

</dl>
Close default summary list code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for default summary list
Name Type Required Description
Name rows Type array Required true Description Array of row item objects.
Name rows[].classes Type string Required false Description Classes to add to the row `div`.
Name rows[].key.text Type string Required true Description If `html` is set, this is not required. Text to use within the each key. If `html` is provided, the `text` argument will be ignored.
Name rows[].key.html Type string Required true Description
Name rows[].key.classes Type string Required false Description Classes to add to the key wrapper.
Name rows[].value.text Type string Required true Description If `html` is set, this is not required. Text to use within the each value. If `html` is provided, the `text` argument will be ignored.
Name rows[].value.html Type string Required true Description If `text` is set, this is not required. HTML to use within the each value. If `html` is provided, the `text` argument will be ignored.
Name rows[].value.classes Type string Required false Description Classes to add to the value wrapper.
Name rows[].actions.classes Type string Required false Description Classes to add to the actions wrapper.
Name rows[].actions.items Type array Required false Description Array of action item objects.
Name actions.items[].href Type string Required true Description The value of the link href attribute for an action item.
Name actions.items[].text Type string Required true Description If `html` is set, this is not required. Text to use within each action item. If `html` is provided, the `text` argument will be ignored.
Name actions.items[].html Type string Required true Description If `text` is set, this is not required. HTML to use within the each action item. If `html` is provided, the `text` argument will be ignored.
Name actions.items[].visuallyHiddenText Type string Required false Description Actions rely on context from the surrounding content so may require additional accessible text, text supplied to this option is appended to the end, use `html` for more complicated scenarios.
Name classes Type string Required false Description Classes to add to the summary list container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the summary list container.
Copy default summary list code 
{% from "summary-list/macro.njk" import summaryList %}

{{ summaryList({
  rows: [
    {
      key: {
        text: "Name"
      },
      value: {
        text: "Tom Smith"
      },
      actions: {
        items: [
          {
            href: "#",
            text: "Change",
            visuallyHiddenText: "name"
          }
        ]
      }
    },
    {
      key: {
        text: "Date of birth"
      },
      value: {
        text: "26 June 1990"
      },
      actions: {
        items: [
          {
            href: "#",
            text: "Change",
            visuallyHiddenText: "date of birth"
          }
        ]
      }
    },
    {
      key: {
        text: "Contact information"
      },
      value: {
        html: "2 Snow Hill<br>Birmingham<br> B4 6GA"
      },
      actions: {
        items: [
          {
            href: "#",
            text: "Change",
            visuallyHiddenText: "contact information"
          }
        ]
      }
    },
    {
      key: {
        text: "Contact details"
      },
      value: {
        html: '<p>07123 456789</p><p>tom.smith@example.com</p>'
      },
      actions: {
        items: [
          {
            href: "#",
            text: "Change",
            visuallyHiddenText: "contact details"
          }
        ]
      }
    }
  ]
}) }}
Close default summary list code

Summary list without actions

Open this without action summary list example in new window
Copy without action summary list code 
<dl class="hs2-summary-list">

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Name
    </dt>
    <dd class="hs2-summary-list__value">
      Tom Smith
    </dd>

  </div>

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Date of birth
    </dt>
    <dd class="hs2-summary-list__value">
      26 June 1990
    </dd>

  </div>

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Contact information
    </dt>
    <dd class="hs2-summary-list__value">
      2 Snow Hill<br>Birmingham<br> B4 6GA
    </dd>

  </div>

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Contact details
    </dt>
    <dd class="hs2-summary-list__value">
      <p>07123 456789</p>
      <p>tom.smith@example.com</p>
    </dd>

  </div>

</dl>
Close without action summary list code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for without action summary list
Name Type Required Description
Name rows Type array Required true Description Array of row item objects.
Name rows[].classes Type string Required false Description Classes to add to the row `div`.
Name rows[].key.text Type string Required true Description If `html` is set, this is not required. Text to use within the each key. If `html` is provided, the `text` argument will be ignored.
Name rows[].key.html Type string Required true Description
Name rows[].key.classes Type string Required false Description Classes to add to the key wrapper.
Name rows[].value.text Type string Required true Description If `html` is set, this is not required. Text to use within the each value. If `html` is provided, the `text` argument will be ignored.
Name rows[].value.html Type string Required true Description If `text` is set, this is not required. HTML to use within the each value. If `html` is provided, the `text` argument will be ignored.
Name rows[].value.classes Type string Required false Description Classes to add to the value wrapper.
Name rows[].actions.classes Type string Required false Description Classes to add to the actions wrapper.
Name rows[].actions.items Type array Required false Description Array of action item objects.
Name actions.items[].href Type string Required true Description The value of the link href attribute for an action item.
Name actions.items[].text Type string Required true Description If `html` is set, this is not required. Text to use within each action item. If `html` is provided, the `text` argument will be ignored.
Name actions.items[].html Type string Required true Description If `text` is set, this is not required. HTML to use within the each action item. If `html` is provided, the `text` argument will be ignored.
Name actions.items[].visuallyHiddenText Type string Required false Description Actions rely on context from the surrounding content so may require additional accessible text, text supplied to this option is appended to the end, use `html` for more complicated scenarios.
Name classes Type string Required false Description Classes to add to the summary list container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the summary list container.
Copy without action summary list code 
{% from "summary-list/macro.njk" import summaryList %}

{{ summaryList({
  rows: [
    {
      key: {
        text: "Name"
      },
      value: {
        text: "	Tom Smith"
      }
    },
    {
      key: {
        text: "Date of birth"
      },
      value: {
        text: "26 June 1990"
      }
    },
    {
      key: {
        text: "Contact information"
      },
      value: {
        html: "	2 Snow Hill<br>Birmingham<br> B4 6GA"
      }
    },
    {
      key: {
        text: "Contact details"
      },
      value: {
        html: '<p>07123 456789</p><p>tom.smith@example.com</p>'
      }
    }
  ]
}) }}
Close without action summary list code

Summary list without actions or borders

If you do not include actions in your summary list and it would be better for your design to remove the separating borders, use the hs2-summary-list--no-border class.

Open this without border summary list example in new window
Copy without border summary list code 
<dl class="hs2-summary-list hs2-summary-list--no-border">

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Name
    </dt>
    <dd class="hs2-summary-list__value">
      Tom Smith
    </dd>

  </div>

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Date of birth
    </dt>
    <dd class="hs2-summary-list__value">
      26 June 1990
    </dd>

  </div>

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Contact information
    </dt>
    <dd class="hs2-summary-list__value">
      2 Snow Hill<br>Birmingham<br> B4 6GA
    </dd>

  </div>

  <div class="hs2-summary-list__row">
    <dt class="hs2-summary-list__key">
      Contact details
    </dt>
    <dd class="hs2-summary-list__value">
      <p>07123 456789</p>
      <p>tom.smith@example.com</p>
    </dd>

  </div>

</dl>
Close without border summary list code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for without border summary list
Name Type Required Description
Name rows Type array Required true Description Array of row item objects.
Name rows[].classes Type string Required false Description Classes to add to the row `div`.
Name rows[].key.text Type string Required true Description If `html` is set, this is not required. Text to use within the each key. If `html` is provided, the `text` argument will be ignored.
Name rows[].key.html Type string Required true Description
Name rows[].key.classes Type string Required false Description Classes to add to the key wrapper.
Name rows[].value.text Type string Required true Description If `html` is set, this is not required. Text to use within the each value. If `html` is provided, the `text` argument will be ignored.
Name rows[].value.html Type string Required true Description If `text` is set, this is not required. HTML to use within the each value. If `html` is provided, the `text` argument will be ignored.
Name rows[].value.classes Type string Required false Description Classes to add to the value wrapper.
Name rows[].actions.classes Type string Required false Description Classes to add to the actions wrapper.
Name rows[].actions.items Type array Required false Description Array of action item objects.
Name actions.items[].href Type string Required true Description The value of the link href attribute for an action item.
Name actions.items[].text Type string Required true Description If `html` is set, this is not required. Text to use within each action item. If `html` is provided, the `text` argument will be ignored.
Name actions.items[].html Type string Required true Description If `text` is set, this is not required. HTML to use within the each action item. If `html` is provided, the `text` argument will be ignored.
Name actions.items[].visuallyHiddenText Type string Required false Description Actions rely on context from the surrounding content so may require additional accessible text, text supplied to this option is appended to the end, use `html` for more complicated scenarios.
Name classes Type string Required false Description Classes to add to the summary list container.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the summary list container.
Copy without border summary list code 
{% from "summary-list/macro.njk" import summaryList %}

{{ summaryList({
  classes: 'hs2-summary-list--no-border',
  rows: [
    {
      key: {
        text: "Name"
      },
      value: {
        text: "	Tom Smith"
      }
    },
    {
      key: {
        text: "Date of birth"
      },
      value: {
        text: "	26 June 1990"
      }
    },
    {
      key: {
        text: "Contact information"
      },
      value: {
        html: "2 Snow Hill<br>Birmingham<br> B4 6GA"
      }
    },
    {
      key: {
        text: "Contact details"
      },
      value: {
        html: '<p>07123 456789</p><p>tom.smith@example.com</p>'
      }
    }
  ]
}) }}
Close without border summary list code