Cookies on ons.gov.uk

Cookies are small files stored on your device when you visit a website. We use some essential cookies to make this website work.

We would like to set additional cookies to remember your settings and understand how you use the site. This helps us to improve our services.

You have accepted all additional cookies. You have rejected all additional cookies. You can change your cookie preferences at any time.

Skip to main content

Document list

Overview

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.

Important information:
This component requires documentation.

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.

Warning:

Always use HTML web pages to publish documents where possible. Any downloadable document must meet accessibility standards such as those described in our guidance on designing accessible PDFs

Example Document List Downloads contents

Nunjucks
{% from "components/document-list/_macro.njk" import onsDocumentList %}
{{
    onsDocumentList({
        "documents": [
            {
                "thumbnail": true,
                "title": {
                    "text": 'Including everyone in Census 2021',
                    "url": '#0'
                },
                "metadata": {
                    "object": {
                      "text": 'Poster'
                    },
                    "file": {
                        "fileType": 'PDF',
                        "fileSize": '499KB',
                        "filePages": '1 page'
                    }
                },
                "description": 'Empty belly poster, aimed at advertising census events.'
            },
            {
                "thumbnail": true,
                "title": {
                    "text": 'Community handbook for Census 2021',
                    "url": '#0'
                },
                "metadata": {
                    "object": {
                        "text": 'Booklet'
                    },
                    "file": {
                        "fileType": 'PDF',
                        "fileSize": '3.3MB',
                        "filePages": '16 pages'
                    }
                },
                "description": 'This handbook explains what the census is, why it matters to everyone and how we can work together to spread the word within your community.'
            },
            {
                "thumbnail": true,
                "title": {
                    "text": 'Census 2021 matters to everyone',
                    "url": '#0'
                },
                "metadata": {
                    "object": {
                        "text": 'Poster'
                    },
                    "file": {
                        "fileType": 'PDF',
                        "fileSize": '866KB',
                        "filePages": '1 page'
                    }
                },
                "description": 'By taking part and encouraging others to do the same, you’ll make sure your community gets the services it needs.'
            }
        ]
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
idstringfalseThe HTML id attribute for the document list element
classesstringfalseClasses for the document list element
attributesobjectfalseHTML attributes (for example, data attributes) to add to the document list element
documentsArray<Document>trueAn array of document items in the documents list
headingLevelintfalseNumber used to determine the heading level of the list item title. Use to ensure the title has a correct semantic order on the page. Defaults to 2
Document
NameTypeRequiredDescription
classesstringfalseCustom classes to add to each document list item
attributesobjectfalseHTML attributes (for example, data attributes) to add to each document list item
titleObject<Title>trueAn object containing text and url of the title
descriptionstringfalseA short HTML extract of text (for example, a short sentence to give some context of the document)
thumbnailObject<Thumbnail>falseAn object containing path and filename attributes for the thumbnail image. Renders a placeholder instead if set to true
metadataObject<Metadata>falseAn object for a list of information about document, for example, date, type and size
featuredbooleanfalseWill render a featured variant of the document if set to true
fullWidthbooleanfalseIf set to true, wraps the featured document in a div with class ons-container for a “full-bleed” layout. Can only be set when featured is set to true.
widebooleanfalseSet to true to increase the maximum width of the layout container to 1280px.
Thumbnail
NameTypeRequiredDescription
smallSrcstringtruePath to the non-retina version of the image
largeSrcstringtruePath to the retina version of the image
Metadata
NameTypeRequiredDescription
objectObject<Object>falseAn object for a list item describing the type of document, for example, “Dataset” or “Press release”
dateObject<Date>falseAn object for the date the document was published or updated
fileObject<File>falseAn object to describe the details of the downloadable file such as format and size
Object
NameTypeRequiredDescription
textstringtrueLabel for the type of document, for example “User requested data”.
urlstringfalseURL href for the type. Can be used to filter a list of documents by category.
refstringfalseText for a sub-type or reference. Can be used to give extra detail about the type, for example, “User requested data: Ref 008052”.
Date
NameTypeRequiredDescription
isostringtrueISO format meachine-readable date, for example, 2020-05-20
shortstringtrueDisplayed short format of the date, for example, “20 May 2020”
prefixstringfalseLabel to prefix the date for context, for example, “Last updated” (Defaults to “Published”). Is automatically suffixed with a colon.
showPrefixbooleanfalseDisplays the prefix when set to true. Otherwise it will be hidden. Use when context is required.
File
NameTypeRequiredDescription
fileTypestringtrueFormat of the file, for example, PDF, DOC, XLS
fileSizestringtrueSize of the file in megabytes or kilobytes, for example, “850KB”
filePagesstringfalseNumber of pages in the file, for example, “16 pages”
Title
NameTypeRequiredDescription
textstringtrueThe title for the document
urlstringtrueThe URL for the document link (either a file or web page)
HTML
<ul class="ons-document-list">
  <li class="ons-document-list__item">
    <div class="ons-document-list__item-image ons-document-list__item-image--file" aria-hidden="true">
      <a class="ons-document-list__image-link ons-document-list__image-link--placeholder" href="#0" tabindex="-1">
      </a>
    </div>
    <div class="ons-document-list__item-content">
      <div class="ons-document-list__item-header">
        <h2 class="ons-document-list__item-title ons-u-fs-m ons-u-mt-no ons-u-mb-2xs">
          <a href="#0">Including everyone in Census 2021<span class="ons-u-vh"> , PDF document download, 499KB, 1 page
            </span>
          </a>
        </h2>
        <ul class="ons-document-list__item-metadata ons-u-mb-2xs">
          <li class="ons-document-list__item-attribute ons-u-mr-no">
            <span>Poster,</span>
          </li>
          <li class="ons-document-list__item-attribute" aria-hidden="true"> PDF, 499KB, 1 page </li>
        </ul>
      </div>
      <div class="ons-document-list__item-description">Empty belly poster, aimed at advertising census events.</div>
    </div>
  </li>
  <li class="ons-document-list__item">
    <div class="ons-document-list__item-image ons-document-list__item-image--file" aria-hidden="true">
      <a class="ons-document-list__image-link ons-document-list__image-link--placeholder" href="#0" tabindex="-1">
      </a>
    </div>
    <div class="ons-document-list__item-content">
      <div class="ons-document-list__item-header">
        <h2 class="ons-document-list__item-title ons-u-fs-m ons-u-mt-no ons-u-mb-2xs">
          <a href="#0">Community handbook for Census 2021<span class="ons-u-vh"> , PDF document download, 3.3MB, 16
              pages </span>
          </a>
        </h2>
        <ul class="ons-document-list__item-metadata ons-u-mb-2xs">
          <li class="ons-document-list__item-attribute ons-u-mr-no">
            <span>Booklet,</span>
          </li>
          <li class="ons-document-list__item-attribute" aria-hidden="true"> PDF, 3.3MB, 16 pages </li>
        </ul>
      </div>
      <div class="ons-document-list__item-description">This handbook explains what the census is, why it matters to
        everyone and how we can work together to spread the word within your community.</div>
    </div>
  </li>
  <li class="ons-document-list__item">
    <div class="ons-document-list__item-image ons-document-list__item-image--file" aria-hidden="true">
      <a class="ons-document-list__image-link ons-document-list__image-link--placeholder" href="#0" tabindex="-1">
      </a>
    </div>
    <div class="ons-document-list__item-content">
      <div class="ons-document-list__item-header">
        <h2 class="ons-document-list__item-title ons-u-fs-m ons-u-mt-no ons-u-mb-2xs">
          <a href="#0">Census 2021 matters to everyone<span class="ons-u-vh"> , PDF document download, 866KB, 1 page
            </span>
          </a>
        </h2>
        <ul class="ons-document-list__item-metadata ons-u-mb-2xs">
          <li class="ons-document-list__item-attribute ons-u-mr-no">
            <span>Poster,</span>
          </li>
          <li class="ons-document-list__item-attribute" aria-hidden="true"> PDF, 866KB, 1 page </li>
        </ul>
      </div>
      <div class="ons-document-list__item-description">By taking part and encouraging others to do the same, you’ll make
        sure your community gets the services it needs.</div>
    </div>
  </li>
</ul>

Search results

Use this variant to build an index of search results.

Example Document List Search Results contents

Nunjucks
{% from "components/document-list/_macro.njk" import onsDocumentList %}

{{
    onsDocumentList({
        "documents": [
            {
                "featured": true,
                "showMetadataFirst": true,
                "title": {
                    "text": 'Crime and justice',
                    "url": '#0'
                },
                "metadata": {
                    "object": {
                        "text": 'Topic'
                    }
                },
                "description": '<p>Figures on <mark>crime</mark> levels and trends for England and Wales based primarily on two sets of statistics: the <mark>Crime</mark> Survey for England and Wales (CSEW) and police recorded <mark>crime</mark> data.</p>
                <p>View all <a href="#0">datasets</a> or <a href="#0">publications</a> related to <a href="#0">Crime and justice</a></p>'
            },
            {
                "title": {
                    "text": 'Disability and crime',
                    "url": '#0'
                },
                "metadata": {
                    "object": {
                        "text": 'Dataset'
                    },
                    "date": {
                        "prefix": 'Released',
                        "showPrefix": true,
                        "iso": '2021-02-18',
                        "short": '18 February 2021'
                    }
                },
                "description": '<p>Domestic abuse and sexual assault outcomes for disabled people in England and Wales aged 16 to 59 years, with analysis by age, sex, impairment type, impairment severity, country and region using the <mark>Crime</mark> Survey for England and Wales (CSEW) data.</p>'
            },
            {
                "title": {
                    "text": 'Disability and crime, UK: 2019 (Latest release)',
                    "url": '#0'
                },
                "metadata": {
                    "object": {
                        "text": 'Statistical bulletin'
                    },
                    "date": {
                        "prefix": 'Released',
                        "showPrefix": true,
                        "iso": '2019-12-01',
                        "short": '2 December 2019'
                    }
                },
                "description": '<p>An overview of published data on disability and <mark>crime</mark> in the UK and analysis of the experience of domestic abuse and sexual assault for disabled adults aged 16 to 59 years in England and Wales. Analysis by age, sex and impairment type.</p>'
            },
            {
                "title": {
                    "text": 'Hate crime by disability status, Crime Survey for England and Wales (CSEW) combined years 2013 and 2014 to 2015 and 2016',
                    "url": '#0'
                },
                "metadata": {
                    "object": {
                        "text": 'User requested data',
                        "ref": 'Ref 008052'
                    },
                    "date": {
                        "prefix": 'Released',
                        "showPrefix": true,
                        "iso": '2017-04-20',
                        "short": '20 April 2017'
                    }
                }
            }
        ]
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
idstringfalseThe HTML id attribute for the document list element
classesstringfalseClasses for the document list element
attributesobjectfalseHTML attributes (for example, data attributes) to add to the document list element
documentsArray<Document>trueAn array of document items in the documents list
headingLevelintfalseNumber used to determine the heading level of the list item title. Use to ensure the title has a correct semantic order on the page. Defaults to 2
Document
NameTypeRequiredDescription
classesstringfalseCustom classes to add to each document list item
attributesobjectfalseHTML attributes (for example, data attributes) to add to each document list item
titleObject<Title>trueAn object containing text and url of the title
descriptionstringfalseA short HTML extract of text (for example, a short sentence to give some context of the document)
thumbnailObject<Thumbnail>falseAn object containing path and filename attributes for the thumbnail image. Renders a placeholder instead if set to true
metadataObject<Metadata>falseAn object for a list of information about document, for example, date, type and size
featuredbooleanfalseWill render a featured variant of the document if set to true
fullWidthbooleanfalseIf set to true, wraps the featured document in a div with class ons-container for a “full-bleed” layout. Can only be set when featured is set to true.
widebooleanfalseSet to true to increase the maximum width of the layout container to 1280px.
Thumbnail
NameTypeRequiredDescription
smallSrcstringtruePath to the non-retina version of the image
largeSrcstringtruePath to the retina version of the image
Metadata
NameTypeRequiredDescription
objectObject<Object>falseAn object for a list item describing the type of document, for example, “Dataset” or “Press release”
dateObject<Date>falseAn object for the date the document was published or updated
fileObject<File>falseAn object to describe the details of the downloadable file such as format and size
Object
NameTypeRequiredDescription
textstringtrueLabel for the type of document, for example “User requested data”.
urlstringfalseURL href for the type. Can be used to filter a list of documents by category.
refstringfalseText for a sub-type or reference. Can be used to give extra detail about the type, for example, “User requested data: Ref 008052”.
Date
NameTypeRequiredDescription
isostringtrueISO format meachine-readable date, for example, 2020-05-20
shortstringtrueDisplayed short format of the date, for example, “20 May 2020”
prefixstringfalseLabel to prefix the date for context, for example, “Last updated” (Defaults to “Published”). Is automatically suffixed with a colon.
showPrefixbooleanfalseDisplays the prefix when set to true. Otherwise it will be hidden. Use when context is required.
File
NameTypeRequiredDescription
fileTypestringtrueFormat of the file, for example, PDF, DOC, XLS
fileSizestringtrueSize of the file in megabytes or kilobytes, for example, “850KB”
filePagesstringfalseNumber of pages in the file, for example, “16 pages”
Title
NameTypeRequiredDescription
textstringtrueThe title for the document
urlstringtrueThe URL for the document link (either a file or web page)
HTML
<ul class="ons-document-list">
  <li class="ons-document-list__item ons-document-list__item--featured">
    <div class="ons-document-list__item-content">
      <div class="ons-document-list__item-header ons-document-list__item-header--reverse">
        <h2 class="ons-document-list__item-title ons-u-fs-m ons-u-mt-no ons-u-mb-2xs">
          <a href="#0">Crime and justice </a>
        </h2>
        <ul class="ons-document-list__item-metadata ons-u-mb-2xs">
          <li class="ons-document-list__item-attribute">
            <span class="ons-u-fw-b">Topic</span>
          </li>
        </ul>
      </div>
      <div class="ons-document-list__item-description">
        <p>Figures on <mark>crime</mark> levels and trends for England and Wales based primarily on two sets of
          statistics: the <mark>Crime</mark> Survey for England and Wales (CSEW) and police recorded <mark>crime</mark>
          data.</p>
        <p>View all <a href="#0">datasets</a> or <a href="#0">publications</a> related to <a href="#0">Crime and
            justice</a></p>
      </div>
    </div>
  </li>
  <li class="ons-document-list__item">
    <div class="ons-document-list__item-content">
      <div class="ons-document-list__item-header">
        <h2 class="ons-document-list__item-title ons-u-fs-m ons-u-mt-no ons-u-mb-2xs">
          <a href="#0">Disability and crime </a>
        </h2>
        <ul class="ons-document-list__item-metadata ons-u-mb-2xs">
          <li class="ons-document-list__item-attribute">
            <span class="ons-u-fw-b">Released: </span><time datetime="2021-02-18">18 February 2021</time>
          </li>
          <li class="ons-document-list__item-attribute">
            <span class="ons-u-fw-b">Dataset</span>
          </li>
        </ul>
      </div>
      <div class="ons-document-list__item-description">
        <p>Domestic abuse and sexual assault outcomes for disabled people in England and Wales aged 16 to 59 years, with
          analysis by age, sex, impairment type, impairment severity, country and region using the <mark>Crime</mark>
          Survey for England and Wales (CSEW) data.</p>
      </div>
    </div>
  </li>
  <li class="ons-document-list__item">
    <div class="ons-document-list__item-content">
      <div class="ons-document-list__item-header">
        <h2 class="ons-document-list__item-title ons-u-fs-m ons-u-mt-no ons-u-mb-2xs">
          <a href="#0">Disability and crime, UK: 2019 (Latest release) </a>
        </h2>
        <ul class="ons-document-list__item-metadata ons-u-mb-2xs">
          <li class="ons-document-list__item-attribute">
            <span class="ons-u-fw-b">Released: </span><time datetime="2019-12-01">2 December 2019</time>
          </li>
          <li class="ons-document-list__item-attribute">
            <span class="ons-u-fw-b">Statistical bulletin</span>
          </li>
        </ul>
      </div>
      <div class="ons-document-list__item-description">
        <p>An overview of published data on disability and <mark>crime</mark> in the UK and analysis of the experience
          of domestic abuse and sexual assault for disabled adults aged 16 to 59 years in England and Wales. Analysis by
          age, sex and impairment type.</p>
      </div>
    </div>
  </li>
  <li class="ons-document-list__item">
    <div class="ons-document-list__item-content">
      <div class="ons-document-list__item-header">
        <h2 class="ons-document-list__item-title ons-u-fs-m ons-u-mt-no ons-u-mb-2xs">
          <a href="#0">Hate crime by disability status, Crime Survey for England and Wales (CSEW) combined years 2013
            and 2014 to 2015 and 2016 </a>
        </h2>
        <ul class="ons-document-list__item-metadata ons-u-mb-no">
          <li class="ons-document-list__item-attribute">
            <span class="ons-u-fw-b">Released: </span><time datetime="2017-04-20">20 April 2017</time>
          </li>
          <li class="ons-document-list__item-attribute">
            <span class="ons-u-fw-b">User requested data:</span>
            <span>Ref 008052</span>
          </li>
        </ul>
      </div>
    </div>
  </li>
</ul>

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.

News articles

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

Example Document List Articles contents

Nunjucks
{% from "components/document-list/_macro.njk" import onsDocumentList %}

{{
    onsDocumentList({
        "documents": [
            {
                "thumbnail": {
                    "smallSrc": '/img/small/census-monuments-lights.jpg',
                    "largeSrc": '/img/large/census-monuments-lights.jpg'
                },
                "title": {
                    "text": 'Landmarks are lighting up purple to mark Census Day',
                    "url": '#0'
                },
                "metadata": {
                    "object": {
                        "text": 'Press releases',
                        "url": '#0'
                    },
                    "date": {
                        "iso": '2022-01-01',
                        "short": '1 January 2022'
                    }
                },
                "description": 'Hundreds of buildings & landmarks across England and Wales are lighting up purple this weekend to celebrate the census and its importance to communities.'
            },
            {
                "thumbnail": {
                    "smallSrc": '/img/small/ons-award-winners.jpg',
                    "largeSrc": '/img/large/ons-award-winners.jpg'
                },
                "title": {
                    "text": 'Office for National Statistics win top Royal Statistical Society award',
                    "url": '#0'
                },
                "metadata": {
                    "object": {
                        "text": 'Press releases',
                        "url": '#0'
                    },
                    "date": {
                        "iso": '2021-07-15',
                        "short": '15 July 2021'
                    }
                },
                "description": 'The Office for National Statistics’ (ONS) analysis showing that people from certain ethnicities had a higher risk of dying from COVID-19 has been recognised by the Royal Statistical Society (RSS) with the renowned Campion Award.'
            },
            {
                "thumbnail": true,
                "title": {
                    "text": 'Five Office for National Statistics names in New Year’s Honours',
                    "url": '#0'
                },
                "metadata": {
                    "object": {
                        "text": 'Press releases',
                        "url": '#0'
                    },
                    "date": {
                        "iso": '2022-01-01',
                        "short": '1 January 2022'
                    }
                },
                "description": 'After another year in which data and statistics have dominated public debate, five Office for National Statistics (ONS) employees have been recognised for their contributions to statistics, public health and the census in the New Year’s Honours list.'
            }
        ]
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
idstringfalseThe HTML id attribute for the document list element
classesstringfalseClasses for the document list element
attributesobjectfalseHTML attributes (for example, data attributes) to add to the document list element
documentsArray<Document>trueAn array of document items in the documents list
headingLevelintfalseNumber used to determine the heading level of the list item title. Use to ensure the title has a correct semantic order on the page. Defaults to 2
Document
NameTypeRequiredDescription
classesstringfalseCustom classes to add to each document list item
attributesobjectfalseHTML attributes (for example, data attributes) to add to each document list item
titleObject<Title>trueAn object containing text and url of the title
descriptionstringfalseA short HTML extract of text (for example, a short sentence to give some context of the document)
thumbnailObject<Thumbnail>falseAn object containing path and filename attributes for the thumbnail image. Renders a placeholder instead if set to true
metadataObject<Metadata>falseAn object for a list of information about document, for example, date, type and size
featuredbooleanfalseWill render a featured variant of the document if set to true
fullWidthbooleanfalseIf set to true, wraps the featured document in a div with class ons-container for a “full-bleed” layout. Can only be set when featured is set to true.
widebooleanfalseSet to true to increase the maximum width of the layout container to 1280px.
Thumbnail
NameTypeRequiredDescription
smallSrcstringtruePath to the non-retina version of the image
largeSrcstringtruePath to the retina version of the image
Metadata
NameTypeRequiredDescription
objectObject<Object>falseAn object for a list item describing the type of document, for example, “Dataset” or “Press release”
dateObject<Date>falseAn object for the date the document was published or updated
fileObject<File>falseAn object to describe the details of the downloadable file such as format and size
Object
NameTypeRequiredDescription
textstringtrueLabel for the type of document, for example “User requested data”.
urlstringfalseURL href for the type. Can be used to filter a list of documents by category.
refstringfalseText for a sub-type or reference. Can be used to give extra detail about the type, for example, “User requested data: Ref 008052”.
Date
NameTypeRequiredDescription
isostringtrueISO format meachine-readable date, for example, 2020-05-20
shortstringtrueDisplayed short format of the date, for example, “20 May 2020”
prefixstringfalseLabel to prefix the date for context, for example, “Last updated” (Defaults to “Published”). Is automatically suffixed with a colon.
showPrefixbooleanfalseDisplays the prefix when set to true. Otherwise it will be hidden. Use when context is required.
File
NameTypeRequiredDescription
fileTypestringtrueFormat of the file, for example, PDF, DOC, XLS
fileSizestringtrueSize of the file in megabytes or kilobytes, for example, “850KB”
filePagesstringfalseNumber of pages in the file, for example, “16 pages”
Title
NameTypeRequiredDescription
textstringtrueThe title for the document
urlstringtrueThe URL for the document link (either a file or web page)
HTML
<ul class="ons-document-list">
  <li class="ons-document-list__item">
    <div class="ons-document-list__item-image" aria-hidden="true">
      <a class="ons-document-list__image-link" href="#0" tabindex="-1">
        <img srcset="/img/small/census-monuments-lights.jpg 1x, /img/large/census-monuments-lights.jpg 2x"
          src="/img/small/census-monuments-lights.jpg" alt="" loading="lazy" />
      </a>
    </div>
    <div class="ons-document-list__item-content">
      <div class="ons-document-list__item-header">
        <h2 class="ons-document-list__item-title ons-u-fs-m ons-u-mt-no ons-u-mb-2xs">
          <a href="#0">Landmarks are lighting up purple to mark Census Day </a>
        </h2>
        <ul class="ons-document-list__item-metadata ons-u-mb-2xs">
          <li class="ons-document-list__item-attribute">
            <span class="ons-u-vh">Published: </span><time datetime="2022-01-01">1 January 2022</time>
          </li>
          <li class="ons-document-list__item-attribute">
            <a class="ons-document-list__attribute-link" href="#0">
              <span>Press releases</span>
            </a>
          </li>
        </ul>
      </div>
      <div class="ons-document-list__item-description">Hundreds of buildings & landmarks across England and Wales are
        lighting up purple this weekend to celebrate the census and its importance to communities.</div>
    </div>
  </li>
  <li class="ons-document-list__item">
    <div class="ons-document-list__item-image" aria-hidden="true">
      <a class="ons-document-list__image-link" href="#0" tabindex="-1">
        <img srcset="/img/small/ons-award-winners.jpg 1x, /img/large/ons-award-winners.jpg 2x"
          src="/img/small/ons-award-winners.jpg" alt="" loading="lazy" />
      </a>
    </div>
    <div class="ons-document-list__item-content">
      <div class="ons-document-list__item-header">
        <h2 class="ons-document-list__item-title ons-u-fs-m ons-u-mt-no ons-u-mb-2xs">
          <a href="#0">Office for National Statistics win top Royal Statistical Society award </a>
        </h2>
        <ul class="ons-document-list__item-metadata ons-u-mb-2xs">
          <li class="ons-document-list__item-attribute">
            <span class="ons-u-vh">Published: </span><time datetime="2021-07-15">15 July 2021</time>
          </li>
          <li class="ons-document-list__item-attribute">
            <a class="ons-document-list__attribute-link" href="#0">
              <span>Press releases</span>
            </a>
          </li>
        </ul>
      </div>
      <div class="ons-document-list__item-description">The Office for National Statistics’ (ONS) analysis showing that
        people from certain ethnicities had a higher risk of dying from COVID-19 has been recognised by the Royal
        Statistical Society (RSS) with the renowned Campion Award.</div>
    </div>
  </li>
  <li class="ons-document-list__item">
    <div class="ons-document-list__item-image" aria-hidden="true">
      <a class="ons-document-list__image-link ons-document-list__image-link--placeholder" href="#0" tabindex="-1">
      </a>
    </div>
    <div class="ons-document-list__item-content">
      <div class="ons-document-list__item-header">
        <h2 class="ons-document-list__item-title ons-u-fs-m ons-u-mt-no ons-u-mb-2xs">
          <a href="#0">Five Office for National Statistics names in New Year’s Honours </a>
        </h2>
        <ul class="ons-document-list__item-metadata ons-u-mb-2xs">
          <li class="ons-document-list__item-attribute">
            <span class="ons-u-vh">Published: </span><time datetime="2022-01-01">1 January 2022</time>
          </li>
          <li class="ons-document-list__item-attribute">
            <a class="ons-document-list__attribute-link" href="#0">
              <span>Press releases</span>
            </a>
          </li>
        </ul>
      </div>
      <div class="ons-document-list__item-description">After another year in which data and statistics have dominated
        public debate, five Office for National Statistics (ONS) employees have been recognised for their contributions
        to statistics, public health and the census in the New Year’s Honours list.</div>
    </div>
  </li>
</ul>

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.

Example Document List Article Featured contents
Nunjucks
{% from "components/document-list/_macro.njk" import onsDocumentList %}

{{
    onsDocumentList({
        "documents": [
            {
                "featured": true,
                "fullWidth": true,
                "thumbnail": {
                    "smallSrc": '/img/small/census-monuments-lights-featured.jpg',
                    "largeSrc": '/img/large/census-monuments-lights-featured.jpg'
                },
                "title": {
                    "text": 'Landmarks are lighting up purple to mark Census Day',
                    "url": '#0'
                },
                "metadata": {
                    "object": {
                        "text": 'Press releases',
                        "url": '#0'
                    },
                    "date": {
                        "iso": '2022-01-01',
                        "short": '1 January 2022'
                    }
                },
                "description": 'Hundreds of buildings & landmarks across England and Wales are lighting up purple this weekend to celebrate the census and its importance to communities.'
            }
        ]
    })
}}
Nunjucks macro options
NameTypeRequiredDescription
idstringfalseThe HTML id attribute for the document list element
classesstringfalseClasses for the document list element
attributesobjectfalseHTML attributes (for example, data attributes) to add to the document list element
documentsArray<Document>trueAn array of document items in the documents list
headingLevelintfalseNumber used to determine the heading level of the list item title. Use to ensure the title has a correct semantic order on the page. Defaults to 2
Document
NameTypeRequiredDescription
classesstringfalseCustom classes to add to each document list item
attributesobjectfalseHTML attributes (for example, data attributes) to add to each document list item
titleObject<Title>trueAn object containing text and url of the title
descriptionstringfalseA short HTML extract of text (for example, a short sentence to give some context of the document)
thumbnailObject<Thumbnail>falseAn object containing path and filename attributes for the thumbnail image. Renders a placeholder instead if set to true
metadataObject<Metadata>falseAn object for a list of information about document, for example, date, type and size
featuredbooleanfalseWill render a featured variant of the document if set to true
fullWidthbooleanfalseIf set to true, wraps the featured document in a div with class ons-container for a “full-bleed” layout. Can only be set when featured is set to true.
widebooleanfalseSet to true to increase the maximum width of the layout container to 1280px.
Thumbnail
NameTypeRequiredDescription
smallSrcstringtruePath to the non-retina version of the image
largeSrcstringtruePath to the retina version of the image
Metadata
NameTypeRequiredDescription
objectObject<Object>falseAn object for a list item describing the type of document, for example, “Dataset” or “Press release”
dateObject<Date>falseAn object for the date the document was published or updated
fileObject<File>falseAn object to describe the details of the downloadable file such as format and size
Object
NameTypeRequiredDescription
textstringtrueLabel for the type of document, for example “User requested data”.
urlstringfalseURL href for the type. Can be used to filter a list of documents by category.
refstringfalseText for a sub-type or reference. Can be used to give extra detail about the type, for example, “User requested data: Ref 008052”.
Date
NameTypeRequiredDescription
isostringtrueISO format meachine-readable date, for example, 2020-05-20
shortstringtrueDisplayed short format of the date, for example, “20 May 2020”
prefixstringfalseLabel to prefix the date for context, for example, “Last updated” (Defaults to “Published”). Is automatically suffixed with a colon.
showPrefixbooleanfalseDisplays the prefix when set to true. Otherwise it will be hidden. Use when context is required.
File
NameTypeRequiredDescription
fileTypestringtrueFormat of the file, for example, PDF, DOC, XLS
fileSizestringtrueSize of the file in megabytes or kilobytes, for example, “850KB”
filePagesstringfalseNumber of pages in the file, for example, “16 pages”
Title
NameTypeRequiredDescription
textstringtrueThe title for the document
urlstringtrueThe URL for the document link (either a file or web page)
HTML
<ul class="ons-document-list">
  <li class="ons-document-list__item ons-document-list__item--featured ons-document-list__item--full-width">
    <div class="ons-container">
      <div class="ons-document-list__item-image" aria-hidden="true">
        <a class="ons-document-list__image-link" href="#0" tabindex="-1">
          <img
            srcset="/img/small/census-monuments-lights-featured.jpg 1x, /img/large/census-monuments-lights-featured.jpg 2x"
            src="/img/small/census-monuments-lights-featured.jpg" alt="" loading="lazy" />
        </a>
      </div>
      <div class="ons-document-list__item-content">
        <div class="ons-document-list__item-header">
          <h2 class="ons-document-list__item-title ons-u-fs-m ons-u-mt-no ons-u-mb-2xs">
            <a href="#0">Landmarks are lighting up purple to mark Census Day </a>
          </h2>
          <ul class="ons-document-list__item-metadata ons-u-mb-2xs">
            <li class="ons-document-list__item-attribute">
              <span class="ons-u-vh">Published: </span><time datetime="2022-01-01">1 January 2022</time>
            </li>
            <li class="ons-document-list__item-attribute">
              <a class="ons-document-list__attribute-link" href="#0">
                <span>Press releases</span>
              </a>
            </li>
          </ul>
        </div>
        <div class="ons-document-list__item-description">Hundreds of buildings & landmarks across England and Wales are
          lighting up purple this weekend to celebrate the census and its importance to communities.</div>
      </div>
    </div>
  </li>
</ul>

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 retina 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)
  • retina 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: 136px x 96px
  • retina screen is: 272px × 192px

Image dimensions for featured news article thumbnails:

  • standard screen is: 379px × 248px
  • retina screen is: 758px × 496px

Help improve this page

Let us know how we could improve this page, or share your user research findings. Discuss the ‘Document list’ component on GitHub (opens in a new tab)