Content presentation - Document list

Creates a list of document items, each with a title, metadata, description and optional thumbnail image. Each document item link can either download a document or link to an HTML page, such as a news article or search result.

Variants

Downloadable documents

Use this variant on a page when there are a small amount of files the user needs to download and print, such as posters and booklets.

Open this downloadable documents document list example in new window
Copy downloadable documents document list code 
<ul class="hs2-document-list">

  <li class="hs2-document-list__item">

    <div class="hs2-document-list__item-image hs2-document-list__item-image--file" aria-hidden="true">
      <a class="hs2-document-list__image-link" href="#" tabindex="-1">

        <img class="w-inherit" srcset="/assets/images/thumbnail_23-05-10_-_DL+IR_HS2_Lorry_Routes_at_Waste_Lane__Solihull.png 1x, /assets/images/thumbnail_23-05-10_-_DL+IR_HS2_Lorry_Routes_at_Waste_Lane__Solihull.png 2x" src="/assets/images/thumbnail_23-05-10_-_DL+IR_HS2_Lorry_Routes_at_Waste_Lane__Solihull.png" alt="" loading="lazy">

      </a>
    </div>

    <div class="hs2-document-list__item-content">

      <div class="hs2-document-list__item-header">

        <h3 class="hs2-document-list__item-title hs2-u-fs-m hs2-u-mt-no hs2-u-mb-xs">
          <a href="#">Recovered appeal: HS2 lorry routes at Waste Lane, Solihull (ref: APP/HS2/19 - 10 May 2023)
            <span class="hs2-u-vh">

              , PDF document download, 499KB, 1 page

            </span></a>
        </h3>

        <ul class="ps-0 hs2-document-list__item-metadata hs2-u-mb-xs">
          <li class="hs2-document-list__item-attribute hs2-u-mr-no">
            <span>Poster,</span>
          </li>

          <li class="hs2-document-list__item-attribute" aria-hidden="true">

            PDF, 499KB, 1 page
          </li>

        </ul>

      </div>

      <div class="hs2-document-list__item-description">Decision letter for a recovered appeal under Schedule 17 to the High Speed Rail (London - West Midlands) Act 2017.</div>

    </div>

  </li>

  <li class="hs2-document-list__item">

    <div class="hs2-document-list__item-image hs2-document-list__item-image--file" aria-hidden="true">
      <a class="hs2-document-list__image-link" href="#" tabindex="-1">

        <img class="w-inherit" srcset="/assets/images/thumbnail_HS2_Response_to_CC_24th_Report.png 1x, /assets/images/thumbnail_HS2_Response_to_CC_24th_Report.png 2x" src="/assets/images/thumbnail_HS2_Response_to_CC_24th_Report.png" alt="" loading="lazy">

      </a>
    </div>

    <div class="hs2-document-list__item-content">

      <div class="hs2-document-list__item-header">

        <h3 class="hs2-document-list__item-title hs2-u-fs-m hs2-u-mt-no hs2-u-mb-xs">
          <a href="#">HS2 Ltd response to Construction Commissioner’s 24th report
            <span class="hs2-u-vh">

              , PDF document download, 3.3MB, 16 pages

            </span></a>
        </h3>

        <ul class="ps-0 hs2-document-list__item-metadata hs2-u-mb-xs">
          <li class="hs2-document-list__item-attribute hs2-u-mr-no">
            <span>Booklet,</span>
          </li>

          <li class="hs2-document-list__item-attribute" aria-hidden="true">

            PDF, 3.3MB, 16 pages
          </li>

        </ul>

      </div>

      <div class="hs2-document-list__item-description">High Speed Two (HS2) Ltd responds to the twenty-third Construction Commissioner's report published in March 2023.</div>

    </div>

  </li>

  <li class="hs2-document-list__item">

    <div class="hs2-document-list__item-image hs2-document-list__item-image--file" aria-hidden="true">
      <a class="hs2-document-list__image-link hs2-document-list__image-link--placeholder" href="#" tabindex="-1">

      </a>
    </div>

    <div class="hs2-document-list__item-content">

      <div class="hs2-document-list__item-header">

        <h3 class="hs2-document-list__item-title hs2-u-fs-m hs2-u-mt-no hs2-u-mb-xs">
          <a href="#">HS2 Ltd response to Residents&#39; Commissioner&#39;s report 17
            <span class="hs2-u-vh">

              , PDF document download, 866KB, 1 page

            </span></a>
        </h3>

        <ul class="ps-0 hs2-document-list__item-metadata hs2-u-mb-xs">
          <li class="hs2-document-list__item-attribute hs2-u-mr-no">
            <span>Poster,</span>
          </li>

          <li class="hs2-document-list__item-attribute" aria-hidden="true">

            PDF, 866KB, 1 page
          </li>

        </ul>

      </div>

      <div class="hs2-document-list__item-description">High Speed Two (HS2) Ltd CEO, Mark Thurston, responds to the seventeenth Residents' Commissioner's report.</div>

    </div>

  </li>

</ul>
Close downloadable documents document 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 downloadable documents document list
Name Type Required Description
Name id Type string Required false Description The HTML id attribute for the document list element
Name classes Type string Required false Description Classes for the document list element
Name attributes Type object Required false Description HTML attributes (for example, data attributes) to add to the document list element
Name documents Type array Required true Description An array of document items in the documents list
Name documents[].classes Type string Required false Description Custom classes to add to each document list item
Name documents[].attributes Type object Required false Description HTML attributes (for example, data attributes) to add to each document list item
Name documents[].title Type string Required true Description The title for the document
Name documents[].url Type string Required true Description The URL for the document link (either a file or web page)
Name documents[].description Type string Required false Description A short HTML extract of text (for example, a short sentence to give some context of the document)
Name documents[].thumbnail Type object Required false Description An object containing path and filename attributes for the thumbnail image. Renders a placeholder instead if set to true
Name thumbnail{}.smallSrc Type string Required true Description Path to the standard version of the image
Name thumbnail{}.largeSrc Type string Required true Description Path to the high resolution version of the image
Name documents[].metadata Type object Required false Description An object for a list of information about document, for example, date, type and size
Name metadata{}.type Type object Required false Description An object for a list item describing the type of document, for example, “Dataset” or “Press release”
Name type{}.text Type string Required true Description Label for the type of document, for example “User requested data”.
Name type{}.url Type string Required false Description URL href for the type. Can be used to filter a list of documents by category.
Name type{}.ref Type string Required false Description Text for a sub-type or reference. Can be used to give extra detail about the type, for example, “User requested data: Ref 008052”.
Name metadata{}.date Type object Required false Description An object for the date the document was published or updated
Name date{}.iso Type string Required true Description ISO format machine-readable date, for example, 2020-05-20
Name date{}.short Type string Required true Description Displayed short format of the date, for example, “20 May 2020”
Name date{}.prefix Type string Required false Description Label to prefix the date for context, for example, “Last updated” (Defaults to “Published”). Is automatically suffixed with a colon.
Name date{}.showPrefix Type boolean Required false Description Displays the prefix when set to true. Otherwise it will be hidden. Use when context is required.
Name metadata{}.file Type object Required false Description An object to describe the details of the downloadable file such as format and size
Name file{}.fileType Type string Required true Description Format of the file, for example, PDF, DOC, XLS
Name file{}.fileSize Type string Required true Description Size of the file in megabytes or kilobytes, for example, “850KB”
Name file{}.filePages Type string Required false Description Number of pages in the file, for example, “16 pages”
Name documents[].featured Type boolean Required false Description Will render a featured variant of the document if set to true
Name documents[].fullWidth Type boolean Required false Description If set to true, wraps the featured document in a div with class hs2-container for a “full-bleed” layout
Name documents[].wide Type boolean Required false Description Set to true to increase the maximum width of the layout container to 1280px.
Name titleTag Type string Required false Description The HTML heading tag to wrap each document list item's title to make sure the headings have the correct semantic order on the page. Defaults to h2
Copy downloadable documents document list code 
{% from 'document-list/macro.njk' import documentList %}

{{ documentList({
    "documents": [
        {
            "thumbnail": {
                "smallSrc": '/assets/images/thumbnail_23-05-10_-_DL+IR_HS2_Lorry_Routes_at_Waste_Lane__Solihull.png',
                "largeSrc": '/assets/images/thumbnail_23-05-10_-_DL+IR_HS2_Lorry_Routes_at_Waste_Lane__Solihull.png'
            },
            "url": '#',            
            "title": 'Recovered appeal: HS2 lorry routes at Waste Lane, Solihull (ref: APP/HS2/19 - 10 May 2023)',
            "metadata": {
                "type": {
                  "text": 'Poster'
                },
                "file": {
                    "fileType": 'PDF',
                    "fileSize": '499KB',
                    "filePages": '1 page'
                }
            },
            "description": 'Decision letter for a recovered appeal under Schedule 17 to the High Speed Rail (London - West Midlands) Act 2017.'
        },
        {
            "thumbnail": {
                "smallSrc": '/assets/images/thumbnail_HS2_Response_to_CC_24th_Report.png',
                "largeSrc": '/assets/images/thumbnail_HS2_Response_to_CC_24th_Report.png'
            },
            "url": '#',            
            "title": 'HS2 Ltd response to Construction Commissioner’s 24th report',
            "metadata": {
                "type": {
                    "text": 'Booklet'
                },
                "file": {
                    "fileType": 'PDF',
                    "fileSize": '3.3MB',
                    "filePages": '16 pages'
                }
            },
            "description": "High Speed Two (HS2) Ltd responds to the twenty-third Construction Commissioner's report published in March 2023."
        },
        {
            "thumbnail": true,
            "url": '#',            
            "title": "HS2 Ltd response to Residents' Commissioner's report 17",
            "metadata": {
                "type": {
                    "text": 'Poster'
                },
                "file": {
                    "fileType": 'PDF',
                    "fileSize": '866KB',
                    "filePages": '1 page'
                }
            },
            "description": "High Speed Two (HS2) Ltd CEO, Mark Thurston, responds to the seventeenth Residents' Commissioner's report."
        }
    ]
}) }}
Close downloadable documents document list code

Search results

Use this variant to build an index of search results.

Open this search results document list example in new window
Copy search results document list code 
<ul class="hs2-document-list">

  <li class="hs2-document-list__item hs2-document-list__item--featured">

    <div class="hs2-document-list__item-content">

      <div class="hs2-document-list__item-header hs2-document-list__item-header--reverse">

        <h3 class="hs2-document-list__item-title hs2-u-fs-m hs2-u-mt-no hs2-u-mb-xs">
          <a href="#0">HS2 Ltd response to Construction Commissioner&#39;s 23rd report

            </span></a>
        </h3>

        <ul class="ps-0 hs2-document-list__item-metadata hs2-u-mb-xs">
          <li class="hs2-document-list__item-attribute">
            <span class="fw-bold">Topic</span>
          </li>
        </ul>

      </div>

      <div class="hs2-document-list__item-description">
        <p><em class="hs2-highlight">High Speed Two</em> (HS2) Ltd responds to the twenty-third Construction Commissioner&apos;s report published in December 2022.</p>
      </div>

    </div>

  </li>

  <li class="hs2-document-list__item">

    <div class="hs2-document-list__item-content">

      <div class="hs2-document-list__item-header">

        <h3 class="hs2-document-list__item-title hs2-u-fs-m hs2-u-mt-no hs2-u-mb-xs">
          <a href="#0">HS2 Crewe to Manchester: supplement to the update on the strategic outline business case

            </span></a>
        </h3>

        <ul class="ps-0 hs2-document-list__item-metadata hs2-u-mb-xs">
          <li class="hs2-document-list__item-attribute">

            <span class="fw-bold">Released: </span><time datetime="2021-02-18">18 February 2021</time>
          </li>

          <li class="hs2-document-list__item-attribute">
            <span class="fw-bold">Dataset</span>
          </li>
        </ul>

      </div>

      <div class="hs2-document-list__item-description">
        <p>Supplement to the update on the SOBC sets out the implications of removing the Golborne Link from the <em class="hs2-highlight">High Speed</em> (Crewe to Manchester) Bill scheme.</p>
      </div>

    </div>

  </li>

  <li class="hs2-document-list__item">

    <div class="hs2-document-list__item-content">

      <div class="hs2-document-list__item-header">

        <h3 class="hs2-document-list__item-title hs2-u-fs-m hs2-u-mt-no hs2-u-mb-xs">
          <a href="#0">HS2 Ltd response to Construction Commissioner&#39;s 20th, 21st and 22nd reports

            </span></a>
        </h3>

        <ul class="ps-0 hs2-document-list__item-metadata hs2-u-mb-xs">
          <li class="hs2-document-list__item-attribute">

            <span class="fw-bold">Released: </span><time datetime="2019-12-01">2 December 2019</time>
          </li>

          <li class="hs2-document-list__item-attribute">
            <span class="fw-bold">Statistical bulletin</span>
          </li>
        </ul>

      </div>

      <div class="hs2-document-list__item-description">
        <p><em class="hs2-highlight">High Speed Two</em> (HS2) Ltd responds to the twentieth, twenty-first and twenty-second Construction Commissioner&apos;s report published in March 2022, June 2022 and September 2022.</p>
      </div>

    </div>

  </li>

  <li class="hs2-document-list__item">

    <div class="hs2-document-list__item-content">

      <div class="hs2-document-list__item-header">

        <h3 class="hs2-document-list__item-title hs2-u-fs-m hs2-u-mt-no hs2-u-mb-xs">
          <a href="#0">High Speed Two 6-monthly report to Parliament: October 2022

            </span></a>
        </h3>

        <ul class="ps-0 hs2-document-list__item-metadata hs2-u-mb-no">
          <li class="hs2-document-list__item-attribute">

            <span class="fw-bold">Released: </span><time datetime="2017-04-20">20 April 2017</time>
          </li>

          <li class="hs2-document-list__item-attribute">
            <span class="fw-bold">User requested data: </span>
            <span>Ref 008052</span>

          </li>
        </ul>

      </div>

    </div>

  </li>

</ul>
Close search results document 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 search results document list
Name Type Required Description
Name id Type string Required false Description The HTML id attribute for the document list element
Name classes Type string Required false Description Classes for the document list element
Name attributes Type object Required false Description HTML attributes (for example, data attributes) to add to the document list element
Name documents Type array Required true Description An array of document items in the documents list
Name documents[].classes Type string Required false Description Custom classes to add to each document list item
Name documents[].attributes Type object Required false Description HTML attributes (for example, data attributes) to add to each document list item
Name documents[].title Type string Required true Description The title for the document
Name documents[].url Type string Required true Description The URL for the document link (either a file or web page)
Name documents[].description Type string Required false Description A short HTML extract of text (for example, a short sentence to give some context of the document)
Name documents[].thumbnail Type object Required false Description An object containing path and filename attributes for the thumbnail image. Renders a placeholder instead if set to true
Name thumbnail{}.smallSrc Type string Required true Description Path to the standard version of the image
Name thumbnail{}.largeSrc Type string Required true Description Path to the high resolution version of the image
Name documents[].metadata Type object Required false Description An object for a list of information about document, for example, date, type and size
Name metadata{}.type Type object Required false Description An object for a list item describing the type of document, for example, “Dataset” or “Press release”
Name type{}.text Type string Required true Description Label for the type of document, for example “User requested data”.
Name type{}.url Type string Required false Description URL href for the type. Can be used to filter a list of documents by category.
Name type{}.ref Type string Required false Description Text for a sub-type or reference. Can be used to give extra detail about the type, for example, “User requested data: Ref 008052”.
Name metadata{}.date Type object Required false Description An object for the date the document was published or updated
Name date{}.iso Type string Required true Description ISO format machine-readable date, for example, 2020-05-20
Name date{}.short Type string Required true Description Displayed short format of the date, for example, “20 May 2020”
Name date{}.prefix Type string Required false Description Label to prefix the date for context, for example, “Last updated” (Defaults to “Published”). Is automatically suffixed with a colon.
Name date{}.showPrefix Type boolean Required false Description Displays the prefix when set to true. Otherwise it will be hidden. Use when context is required.
Name metadata{}.file Type object Required false Description An object to describe the details of the downloadable file such as format and size
Name file{}.fileType Type string Required true Description Format of the file, for example, PDF, DOC, XLS
Name file{}.fileSize Type string Required true Description Size of the file in megabytes or kilobytes, for example, “850KB”
Name file{}.filePages Type string Required false Description Number of pages in the file, for example, “16 pages”
Name documents[].featured Type boolean Required false Description Will render a featured variant of the document if set to true
Name documents[].fullWidth Type boolean Required false Description If set to true, wraps the featured document in a div with class hs2-container for a “full-bleed” layout
Name documents[].wide Type boolean Required false Description Set to true to increase the maximum width of the layout container to 1280px.
Name titleTag Type string Required false Description The HTML heading tag to wrap each document list item's title to make sure the headings have the correct semantic order on the page. Defaults to h2
Copy search results document list code 
{% from 'document-list/macro.njk' import documentList %}

{{ documentList({
    "documents": [
        {
            "featured": true,
            "showMetadataFirst": true,
            "url": '#0',
            "title": "HS2 Ltd response to Construction Commissioner's 23rd report",
            "metadata": {
                "type": {
                    "text": 'Topic'
                }
            },
            "description": '<p><em class="hs2-highlight">High Speed Two</em> (HS2) Ltd responds to the twenty-third Construction Commissioner&apos;s report published in December 2022.</p>'
        },
        {
            "url": '#0',
            "title": 'HS2 Crewe to Manchester: supplement to the update on the strategic outline business case',
            "metadata": {
                "type": {
                    "text": 'Dataset'
                },
                "date": {
                    "prefix": 'Released',
                    "showPrefix": true,
                    "iso": '2021-02-18',
                    "short": '18 February 2021'
                }
            },
            "description": '<p>Supplement to the update on the SOBC sets out the implications of removing the Golborne Link from the <em class="hs2-highlight">High Speed</em> (Crewe to Manchester) Bill scheme.</p>'
        },
        {
            "url": '#0',
            "title": "HS2 Ltd response to Construction Commissioner's 20th, 21st and 22nd reports",
            "metadata": {
                "type": {
                    "text": 'Statistical bulletin'
                },
                "date": {
                    "prefix": 'Released',
                    "showPrefix": true,
                    "iso": '2019-12-01',
                    "short": '2 December 2019'
                }
            },
            "description": '<p><em class="hs2-highlight">High Speed Two</em> (HS2) Ltd responds to the twentieth, twenty-first and twenty-second Construction Commissioner&apos;s report published in March 2022, June 2022 and September 2022.</p>'
        },
        {
            "url": '#0',
            "title": 'High Speed Two 6-monthly report to Parliament: October 2022',
            "metadata": {
                "type": {
                    "text": 'User requested data',
                    "ref": 'Ref 008052'
                },
                "date": {
                    "prefix": 'Released',
                    "showPrefix": true,
                    "iso": '2017-04-20',
                    "short": '20 April 2017'
                }
            }
        }
    ]
}) }}
Close search results document list code

Featured search result

A featured search result to place at the top of the search results list to add emphasis to one chosen item. The featured search result should only appear once on the first page of results.

Open this search results featured document list example in new window
Copy search results featured document list code 
<ul class="hs2-document-list">

  <li class="hs2-document-list__item hs2-document-list__item--featured">

    <div class="hs2-document-list__item-content">

      <div class="hs2-document-list__item-header hs2-document-list__item-header--reverse">

        <h3 class="hs2-document-list__item-title hs2-u-fs-m hs2-u-mt-no hs2-u-mb-xs">
          <a href="#0">HS2 Ltd response to Construction Commissioner&#39;s 23rd report

            </span></a>
        </h3>

        <ul class="ps-0 hs2-document-list__item-metadata hs2-u-mb-xs">
          <li class="hs2-document-list__item-attribute">
            <span class="fw-bold">Topic</span>
          </li>
        </ul>

      </div>

      <div class="hs2-document-list__item-description">
        <p><em class="hs2-highlight">High Speed Two</em> (HS2) Ltd responds to the twenty-third Construction Commissioner&apos;s report published in December 2022.</p>
      </div>

    </div>

  </li>

</ul>
Close search results featured document 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 search results featured document list
Name Type Required Description
Name id Type string Required false Description The HTML id attribute for the document list element
Name classes Type string Required false Description Classes for the document list element
Name attributes Type object Required false Description HTML attributes (for example, data attributes) to add to the document list element
Name documents Type array Required true Description An array of document items in the documents list
Name documents[].classes Type string Required false Description Custom classes to add to each document list item
Name documents[].attributes Type object Required false Description HTML attributes (for example, data attributes) to add to each document list item
Name documents[].title Type string Required true Description The title for the document
Name documents[].url Type string Required true Description The URL for the document link (either a file or web page)
Name documents[].description Type string Required false Description A short HTML extract of text (for example, a short sentence to give some context of the document)
Name documents[].thumbnail Type object Required false Description An object containing path and filename attributes for the thumbnail image. Renders a placeholder instead if set to true
Name thumbnail{}.smallSrc Type string Required true Description Path to the standard version of the image
Name thumbnail{}.largeSrc Type string Required true Description Path to the high resolution version of the image
Name documents[].metadata Type object Required false Description An object for a list of information about document, for example, date, type and size
Name metadata{}.type Type object Required false Description An object for a list item describing the type of document, for example, “Dataset” or “Press release”
Name type{}.text Type string Required true Description Label for the type of document, for example “User requested data”.
Name type{}.url Type string Required false Description URL href for the type. Can be used to filter a list of documents by category.
Name type{}.ref Type string Required false Description Text for a sub-type or reference. Can be used to give extra detail about the type, for example, “User requested data: Ref 008052”.
Name metadata{}.date Type object Required false Description An object for the date the document was published or updated
Name date{}.iso Type string Required true Description ISO format machine-readable date, for example, 2020-05-20
Name date{}.short Type string Required true Description Displayed short format of the date, for example, “20 May 2020”
Name date{}.prefix Type string Required false Description Label to prefix the date for context, for example, “Last updated” (Defaults to “Published”). Is automatically suffixed with a colon.
Name date{}.showPrefix Type boolean Required false Description Displays the prefix when set to true. Otherwise it will be hidden. Use when context is required.
Name metadata{}.file Type object Required false Description An object to describe the details of the downloadable file such as format and size
Name file{}.fileType Type string Required true Description Format of the file, for example, PDF, DOC, XLS
Name file{}.fileSize Type string Required true Description Size of the file in megabytes or kilobytes, for example, “850KB”
Name file{}.filePages Type string Required false Description Number of pages in the file, for example, “16 pages”
Name documents[].featured Type boolean Required false Description Will render a featured variant of the document if set to true
Name documents[].fullWidth Type boolean Required false Description If set to true, wraps the featured document in a div with class hs2-container for a “full-bleed” layout
Name documents[].wide Type boolean Required false Description Set to true to increase the maximum width of the layout container to 1280px.
Name titleTag Type string Required false Description The HTML heading tag to wrap each document list item's title to make sure the headings have the correct semantic order on the page. Defaults to h2
Copy search results featured document list code 
{% from 'document-list/macro.njk' import documentList %}

{{ documentList({
    "documents": [
        {
            "featured": true,
            "showMetadataFirst": true,
            "url": '#0',
            "title": "HS2 Ltd response to Construction Commissioner's 23rd report",
            "metadata": {
                "type": {
                    "text": 'Topic'
                }
            },
            "description": '<p><em class="hs2-highlight">High Speed Two</em> (HS2) Ltd responds to the twenty-third Construction Commissioner&apos;s report published in December 2022.</p>'
        }
    ]
}) }}
Close search results featured document list code

News Articles

Use this variant to build a list of articles for an index in the news pattern.

Open this articles document list example in new window
Copy articles document list code 
<ul class="hs2-document-list">

  <li class="hs2-document-list__item">

    <div class="hs2-document-list__item-image" aria-hidden="true">
      <a class="hs2-document-list__image-link" href="#0" tabindex="-1">

        <img class="w-inherit" srcset="/assets/images/s300_artist-impression-hs2-train-from-side.jpeg 1x, /assets/images/s300_artist-impression-hs2-train-from-side.jpeg 2x" src="/assets/images/s300_artist-impression-hs2-train-from-side.jpeg" alt="" loading="lazy">

      </a>
    </div>

    <div class="hs2-document-list__item-content">

      <div class="hs2-document-list__item-header">

        <h3 class="hs2-document-list__item-title hs2-u-fs-m hs2-u-mt-no hs2-u-mb-xs">
          <a href="#0">Government takes action to ensure Scotland receives best possible HS2 service

            </span></a>
        </h3>

        <ul class="ps-0 hs2-document-list__item-metadata hs2-u-mb-xs">
          <li class="hs2-document-list__item-attribute">

            <span class="hs2-u-vh">Published: </span><time datetime="2022-01-01">1 January 2022</time>
          </li>

          <li class="hs2-document-list__item-attribute">
            <a class="hs2-document-list__attribute-link" href="#0">

              <span>Press releases</span>
            </a>

          </li>
        </ul>

      </div>

      <div class="hs2-document-list__item-description">Intention to remove Golborne Link from HS2 Bill announced with alternative options to be explored.</div>

    </div>

  </li>

  <li class="hs2-document-list__item">

    <div class="hs2-document-list__item-image" aria-hidden="true">
      <a class="hs2-document-list__image-link" href="#0" tabindex="-1">

        <img class="w-inherit" srcset="/assets/images/s300_stewart-jackson-hs2-resident-commissioner-960.jpg 1x, /assets/images/s300_stewart-jackson-hs2-resident-commissioner-960.jpg 2x" src="/assets/images/s300_stewart-jackson-hs2-resident-commissioner-960.jpg" alt="" loading="lazy">

      </a>
    </div>

    <div class="hs2-document-list__item-content">

      <div class="hs2-document-list__item-header">

        <h3 class="hs2-document-list__item-title hs2-u-fs-m hs2-u-mt-no hs2-u-mb-xs">
          <a href="#0">Department for Transport appoints new HS2 Residents&#39; Commissioner

            </span></a>
        </h3>

        <ul class="ps-0 hs2-document-list__item-metadata hs2-u-mb-xs">
          <li class="hs2-document-list__item-attribute">

            <span class="hs2-u-vh">Published: </span><time datetime="2021-07-15">15 July 2021</time>
          </li>

          <li class="hs2-document-list__item-attribute">
            <a class="hs2-document-list__attribute-link" href="#0">

              <span>Press releases</span>
            </a>

          </li>
        </ul>

      </div>

      <div class="hs2-document-list__item-description">Stewart Jackson appointed to ensure the government meets its core principles of respecting people and places as the building of HS2 progresses.</div>

    </div>

  </li>

  <li class="hs2-document-list__item">

    <div class="hs2-document-list__item-image" aria-hidden="true">
      <a class="hs2-document-list__image-link hs2-document-list__image-link--placeholder" href="#0" tabindex="-1">

      </a>
    </div>

    <div class="hs2-document-list__item-content">

      <div class="hs2-document-list__item-header">

        <h3 class="hs2-document-list__item-title hs2-u-fs-m hs2-u-mt-no hs2-u-mb-xs">
          <a href="#0">Search for new HS2 Ltd Chair is relaunched to help drive transformation and level up the country

            </span></a>
        </h3>

        <ul class="ps-0 hs2-document-list__item-metadata hs2-u-mb-xs">
          <li class="hs2-document-list__item-attribute">

            <span class="hs2-u-vh">Published: </span><time datetime="2022-01-01">1 January 2022</time>
          </li>

          <li class="hs2-document-list__item-attribute">
            <a class="hs2-document-list__attribute-link" href="#0">

              <span>Press releases</span>
            </a>

          </li>
        </ul>

      </div>

      <div class="hs2-document-list__item-description">The criteria for the role of HS2 Chair have been updated to appeal to leaders from a wider field of sectors and backgrounds.</div>

    </div>

  </li>

</ul>
Close articles document 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 articles document list
Name Type Required Description
Name id Type string Required false Description The HTML id attribute for the document list element
Name classes Type string Required false Description Classes for the document list element
Name attributes Type object Required false Description HTML attributes (for example, data attributes) to add to the document list element
Name documents Type array Required true Description An array of document items in the documents list
Name documents[].classes Type string Required false Description Custom classes to add to each document list item
Name documents[].attributes Type object Required false Description HTML attributes (for example, data attributes) to add to each document list item
Name documents[].title Type string Required true Description The title for the document
Name documents[].url Type string Required true Description The URL for the document link (either a file or web page)
Name documents[].description Type string Required false Description A short HTML extract of text (for example, a short sentence to give some context of the document)
Name documents[].thumbnail Type object Required false Description An object containing path and filename attributes for the thumbnail image. Renders a placeholder instead if set to true
Name thumbnail{}.smallSrc Type string Required true Description Path to the standard version of the image
Name thumbnail{}.largeSrc Type string Required true Description Path to the high resolution version of the image
Name documents[].metadata Type object Required false Description An object for a list of information about document, for example, date, type and size
Name metadata{}.type Type object Required false Description An object for a list item describing the type of document, for example, “Dataset” or “Press release”
Name type{}.text Type string Required true Description Label for the type of document, for example “User requested data”.
Name type{}.url Type string Required false Description URL href for the type. Can be used to filter a list of documents by category.
Name type{}.ref Type string Required false Description Text for a sub-type or reference. Can be used to give extra detail about the type, for example, “User requested data: Ref 008052”.
Name metadata{}.date Type object Required false Description An object for the date the document was published or updated
Name date{}.iso Type string Required true Description ISO format machine-readable date, for example, 2020-05-20
Name date{}.short Type string Required true Description Displayed short format of the date, for example, “20 May 2020”
Name date{}.prefix Type string Required false Description Label to prefix the date for context, for example, “Last updated” (Defaults to “Published”). Is automatically suffixed with a colon.
Name date{}.showPrefix Type boolean Required false Description Displays the prefix when set to true. Otherwise it will be hidden. Use when context is required.
Name metadata{}.file Type object Required false Description An object to describe the details of the downloadable file such as format and size
Name file{}.fileType Type string Required true Description Format of the file, for example, PDF, DOC, XLS
Name file{}.fileSize Type string Required true Description Size of the file in megabytes or kilobytes, for example, “850KB”
Name file{}.filePages Type string Required false Description Number of pages in the file, for example, “16 pages”
Name documents[].featured Type boolean Required false Description Will render a featured variant of the document if set to true
Name documents[].fullWidth Type boolean Required false Description If set to true, wraps the featured document in a div with class hs2-container for a “full-bleed” layout
Name documents[].wide Type boolean Required false Description Set to true to increase the maximum width of the layout container to 1280px.
Name titleTag Type string Required false Description The HTML heading tag to wrap each document list item's title to make sure the headings have the correct semantic order on the page. Defaults to h2
Copy articles document list code 
{% from 'document-list/macro.njk' import documentList %}

{{ documentList({
    "documents": [
        {
            "thumbnail": {
                "smallSrc": '/assets/images/s300_artist-impression-hs2-train-from-side.jpeg',
                "largeSrc": '/assets/images/s300_artist-impression-hs2-train-from-side.jpeg'
            },
            "url": '#0',
            "title": 'Government takes action to ensure Scotland receives best possible HS2 service',
            "metadata": {
                "type": {
                    "text": 'Press releases',
                    "url": '#0'
                },
                "date": {
                    "iso": '2022-01-01',
                    "short": '1 January 2022'
                }
            },
            "description": 'Intention to remove Golborne Link from HS2 Bill announced with alternative options to be explored.'
        },
        {
            "thumbnail": {
                "smallSrc": '/assets/images/s300_stewart-jackson-hs2-resident-commissioner-960.jpg',
                "largeSrc": '/assets/images/s300_stewart-jackson-hs2-resident-commissioner-960.jpg'
            },
            "url": '#0',
            "title": "Department for Transport appoints new HS2 Residents' Commissioner",
            "metadata": {
                "type": {
                    "text": 'Press releases',
                    "url": '#0'
                },
                "date": {
                    "iso": '2021-07-15',
                    "short": '15 July 2021'
                }
            },
            "description": 'Stewart Jackson appointed to ensure the government meets its core principles of respecting people and places as the building of HS2 progresses.'
        },
        {
            "thumbnail": true,
            "url": '#0',
            "title": 'Search for new HS2 Ltd Chair is relaunched to help drive transformation and level up the country',
            "metadata": {
                "type": {
                    "text": 'Press releases',
                    "url": '#0'
                },
                "date": {
                    "iso": '2022-01-01',
                    "short": '1 January 2022'
                }
            },
            "description": 'The criteria for the role of HS2 Chair have been updated to appeal to leaders from a wider field of sectors and backgrounds.'
        }
    ]
}) }}
Close articles document list code

Featured news article

A featured article to display across the full width of the top of the news index to add emphasis to one chosen item. The featured article should only appear once on the first page of the news index.

Open this article featured document list example in new window
Copy article featured document list code 
<ul class="hs2-document-list">

  <li class="hs2-document-list__item hs2-document-list__item--featured hs2-document-list__item--full-width">

    <div class="hs2-u-padding-left-4 hs2-u-padding-right-4 hs2-container">

      <div class="hs2-document-list__item-image" aria-hidden="true">
        <a class="hs2-document-list__image-link" href="#0" tabindex="-1">

          <img class="w-inherit" srcset="/assets/images/s300_artist-impression-hs2-train-from-side.jpeg 1x, /assets/images/s300_artist-impression-hs2-train-from-side.jpeg 2x" src="/assets/images/s300_artist-impression-hs2-train-from-side.jpeg" alt="" loading="lazy">

        </a>
      </div>

      <div class="hs2-document-list__item-content">

        <div class="hs2-document-list__item-header">

          <h3 class="hs2-document-list__item-title hs2-u-fs-m hs2-u-mt-no hs2-u-mb-xs">
            <a href="#0">Government takes action to ensure Scotland receives best possible HS2 service

              </span></a>
          </h3>

          <ul class="ps-0 hs2-document-list__item-metadata hs2-u-mb-xs">
            <li class="hs2-document-list__item-attribute">

              <span class="hs2-u-vh">Published: </span><time datetime="2022-01-01">1 January 2022</time>
            </li>

            <li class="hs2-document-list__item-attribute">
              <a class="hs2-document-list__attribute-link" href="#0">

                <span>Press releases</span>
              </a>

            </li>
          </ul>

        </div>

        <div class="hs2-document-list__item-description">Intention to remove Golborne Link from HS2 Bill announced with alternative options to be explored.</div>

      </div>

    </div>

  </li>

</ul>
Close article featured document 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 article featured document list
Name Type Required Description
Name id Type string Required false Description The HTML id attribute for the document list element
Name classes Type string Required false Description Classes for the document list element
Name attributes Type object Required false Description HTML attributes (for example, data attributes) to add to the document list element
Name documents Type array Required true Description An array of document items in the documents list
Name documents[].classes Type string Required false Description Custom classes to add to each document list item
Name documents[].attributes Type object Required false Description HTML attributes (for example, data attributes) to add to each document list item
Name documents[].title Type string Required true Description The title for the document
Name documents[].url Type string Required true Description The URL for the document link (either a file or web page)
Name documents[].description Type string Required false Description A short HTML extract of text (for example, a short sentence to give some context of the document)
Name documents[].thumbnail Type object Required false Description An object containing path and filename attributes for the thumbnail image. Renders a placeholder instead if set to true
Name thumbnail{}.smallSrc Type string Required true Description Path to the standard version of the image
Name thumbnail{}.largeSrc Type string Required true Description Path to the high resolution version of the image
Name documents[].metadata Type object Required false Description An object for a list of information about document, for example, date, type and size
Name metadata{}.type Type object Required false Description An object for a list item describing the type of document, for example, “Dataset” or “Press release”
Name type{}.text Type string Required true Description Label for the type of document, for example “User requested data”.
Name type{}.url Type string Required false Description URL href for the type. Can be used to filter a list of documents by category.
Name type{}.ref Type string Required false Description Text for a sub-type or reference. Can be used to give extra detail about the type, for example, “User requested data: Ref 008052”.
Name metadata{}.date Type object Required false Description An object for the date the document was published or updated
Name date{}.iso Type string Required true Description ISO format machine-readable date, for example, 2020-05-20
Name date{}.short Type string Required true Description Displayed short format of the date, for example, “20 May 2020”
Name date{}.prefix Type string Required false Description Label to prefix the date for context, for example, “Last updated” (Defaults to “Published”). Is automatically suffixed with a colon.
Name date{}.showPrefix Type boolean Required false Description Displays the prefix when set to true. Otherwise it will be hidden. Use when context is required.
Name metadata{}.file Type object Required false Description An object to describe the details of the downloadable file such as format and size
Name file{}.fileType Type string Required true Description Format of the file, for example, PDF, DOC, XLS
Name file{}.fileSize Type string Required true Description Size of the file in megabytes or kilobytes, for example, “850KB”
Name file{}.filePages Type string Required false Description Number of pages in the file, for example, “16 pages”
Name documents[].featured Type boolean Required false Description Will render a featured variant of the document if set to true
Name documents[].fullWidth Type boolean Required false Description If set to true, wraps the featured document in a div with class hs2-container for a “full-bleed” layout
Name documents[].wide Type boolean Required false Description Set to true to increase the maximum width of the layout container to 1280px.
Name titleTag Type string Required false Description The HTML heading tag to wrap each document list item's title to make sure the headings have the correct semantic order on the page. Defaults to h2
Copy article featured document list code 
{% from "document-list/macro.njk" import documentList %}

{{ documentList({
    "documents": [
        {
            "featured": true,
            "fullWidth": true,
            "thumbnail": {
                "smallSrc": '/assets/images/s300_artist-impression-hs2-train-from-side.jpeg',
                "largeSrc": '/assets/images/s300_artist-impression-hs2-train-from-side.jpeg'
            },
            "url": '#0',
            "title": 'Government takes action to ensure Scotland receives best possible HS2 service',
            "metadata": {
                "type": {
                    "text": 'Press releases',
                    "url": '#0'
                },
                "date": {
                    "iso": '2022-01-01',
                    "short": '1 January 2022'
                }
            },
            "description": 'Intention to remove Golborne Link from HS2 Bill announced with alternative options to be explored.'
        }
    ]
}) }}
Close article featured document list code

How to use this component

Thumbnail images and placeholders

You will need to set two versions of the thumbnail image, one for standard screens and one double-sized image for high resolution screens.

Set a folder path for both small and large image sources using the smallSrc and largeSrc parameters.

Thumbnail images are considered decorative because they do not convey important information, so are hidden from screen readers by using an empty alt tag.

If a document does not have a suitable image to use, set thumbnail: true to display a placeholder thumbnail. This will make sure the link, metadata and description is aligned with the other documents in the list.

Downloadable document thumbnail images

Always set a thumbnail image for a downloadable document, using the cover or first page of the file. Using a thumbnail helps set the users expectation of the file they download.

Image dimensions for downloadable document thumbnails:

  • standard screen is: 96px (width) × 136px (height)
  • high resolution screen is: 192px × 272px

News article thumbnail images

Only set thumbnails for news articles if most of the articles contain images that help describe the content. Use the same image for the thumbnail as the larger image in the article to reinforce the user’s selection.

Image dimensions for news article thumbnails:

  • standard screen is: 379px × 248px
  • high resolution screen is: 758px × 496px