Use up and down keys to navigate results once you've typed more than two characters. Use the enter key to select a result. Touch device users, explore by touch or with swipe gestures.
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
{% from "components/document-list/_macro.njk" import onsDocumentList %}
{{ onsDocumentList({
"documents": [
{
"thumbnail": true,
"url": '#',
"title": 'Including everyone in Census 2021',
"metadata": {
"type": {
"text": 'Poster'
},
"file": {
"fileType": 'PDF',
"fileSize": '499KB',
"filePages": '1 page'
}
},
"description": 'Empty belly poster, aimed at advertising census events.'
},
{
"thumbnail": true,
"url": '#',
"title": 'Community handbook for Census 2021',
"metadata": {
"type": {
"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,
"url": '#',
"title": 'Census 2021 matters to everyone',
"metadata": {
"type": {
"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
Name
Type
Required
Description
id
string
false
The HTML id attribute for the document list element
classes
string
false
Classes for the document list element
attributes
object
false
HTML attributes (for example, data attributes) to add to the document list element
{% from "components/document-list/_macro.njk" import onsDocumentList %}
{{ onsDocumentList({
"documents": [
{
"featured": true,
"showMetadataFirst": true,
"url": '#0',
"title": 'Crime and justice',
"metadata": {
"type": {
"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>'
},
{
"url": '#0',
"title": 'Disability and crime',
"metadata": {
"type": {
"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>'
},
{
"url": '#0',
"title": 'Disability and crime, UK: 2019 (Latest release)',
"metadata": {
"type": {
"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>'
},
{
"url": '#0',
"title": 'Hate crime by disability status, Crime Survey for England and Wales (CSEW) combined years 2013 and 2014 to 2015 and 2016',
"metadata": {
"type": {
"text": 'User requested data',
"ref": 'Ref 008052'
},
"date": {
"prefix": 'Released',
"showPrefix": true,
"iso": '2017-04-20',
"short": '20 April 2017'
}
}
}
]
}) }}
Nunjucks macro options
Name
Type
Required
Description
id
string
false
The HTML id attribute for the document list element
classes
string
false
Classes for the document list element
attributes
object
false
HTML attributes (for example, data attributes) to add to the document list element
Label for the type of document, for example “User requested data”.
url
string
false
URL href for the type. Can be used to filter a list of documents by category.
ref
string
false
Text for a sub-type or reference. Can be used to give extra detail about the type, for example, “User requested data: Ref 008052”.
Date
Name
Type
Required
Description
iso
string
true
ISO format meachine-readable date, for example, 2020-05-20
short
string
true
Displayed short format of the date, for example, “20 May 2020”
prefix
string
false
Label to prefix the date for context, for example, “Last updated” (Defaults to “Published”). Is automatically suffixed with a colon.
showPrefix
boolean
false
Displays the prefix when set to true. Otherwise it will be hidden. Use when context is required.
File
Name
Type
Required
Description
fileType
string
true
Format of the file, for example, PDF, DOC, XLS
fileSize
string
true
Size of the file in megabytes or kilobytes, for example, “850KB”
filePages
string
false
Number of pages in the file, for example, “16 pages”
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-xs">
<a href="#0">Crime and justice </span></a>
</h2>
<ul class="ons-document-list__item-metadata ons-u-mb-xs">
<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-xs">
<a href="#0">Disability and crime </span></a>
</h2>
<ul class="ons-document-list__item-metadata ons-u-mb-xs">
<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-xs">
<a href="#0">Disability and crime, UK: 2019 (Latest release) </span></a>
</h2>
<ul class="ons-document-list__item-metadata ons-u-mb-xs">
<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-xs">
<a href="#0">Hate crime by disability status, Crime Survey for England and Wales (CSEW) combined years 2013
and 2014 to 2015 and 2016 </span></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>
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.
{% from "components/document-list/_macro.njk" import onsDocumentList %}
{{ onsDocumentList({
"documents": [
{
"featured": true,
"showMetadataFirst": true,
"url": '#0',
"title": 'Crime and justice',
"metadata": {
"type": {
"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 crime 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>'
}
]
}) }}
Nunjucks macro options
Name
Type
Required
Description
id
string
false
The HTML id attribute for the document list element
classes
string
false
Classes for the document list element
attributes
object
false
HTML attributes (for example, data attributes) to add to the document list element
Label for the type of document, for example “User requested data”.
url
string
false
URL href for the type. Can be used to filter a list of documents by category.
ref
string
false
Text for a sub-type or reference. Can be used to give extra detail about the type, for example, “User requested data: Ref 008052”.
Date
Name
Type
Required
Description
iso
string
true
ISO format meachine-readable date, for example, 2020-05-20
short
string
true
Displayed short format of the date, for example, “20 May 2020”
prefix
string
false
Label to prefix the date for context, for example, “Last updated” (Defaults to “Published”). Is automatically suffixed with a colon.
showPrefix
boolean
false
Displays the prefix when set to true. Otherwise it will be hidden. Use when context is required.
File
Name
Type
Required
Description
fileType
string
true
Format of the file, for example, PDF, DOC, XLS
fileSize
string
true
Size of the file in megabytes or kilobytes, for example, “850KB”
filePages
string
false
Number of pages in the file, for example, “16 pages”
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-xs">
<a href="#0">Crime and justice </span></a>
</h2>
<ul class="ons-document-list__item-metadata ons-u-mb-xs">
<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 crime 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>
</ul>
News articles
Use this variant to build a list of articles for an index in the news pattern.
{% 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'
},
"url": '#0',
"title": 'Landmarks are lighting up purple to mark Census Day',
"metadata": {
"type": {
"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'
},
"url": '#0',
"title": 'Office for National Statistics win top Royal Statistical Society award',
"metadata": {
"type": {
"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,
"url": '#0',
"title": 'Five Office for National Statistics names in New Year’s Honours',
"metadata": {
"type": {
"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
Name
Type
Required
Description
id
string
false
The HTML id attribute for the document list element
classes
string
false
Classes for the document list element
attributes
object
false
HTML attributes (for example, data attributes) to add to the document list element
Label for the type of document, for example “User requested data”.
url
string
false
URL href for the type. Can be used to filter a list of documents by category.
ref
string
false
Text for a sub-type or reference. Can be used to give extra detail about the type, for example, “User requested data: Ref 008052”.
Date
Name
Type
Required
Description
iso
string
true
ISO format meachine-readable date, for example, 2020-05-20
short
string
true
Displayed short format of the date, for example, “20 May 2020”
prefix
string
false
Label to prefix the date for context, for example, “Last updated” (Defaults to “Published”). Is automatically suffixed with a colon.
showPrefix
boolean
false
Displays the prefix when set to true. Otherwise it will be hidden. Use when context is required.
File
Name
Type
Required
Description
fileType
string
true
Format of the file, for example, PDF, DOC, XLS
fileSize
string
true
Size of the file in megabytes or kilobytes, for example, “850KB”
filePages
string
false
Number of pages in the file, for example, “16 pages”
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-xs">
<a href="#0">Landmarks are lighting up purple to mark Census Day </span></a>
</h2>
<ul class="ons-document-list__item-metadata ons-u-mb-xs">
<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-xs">
<a href="#0">Office for National Statistics win top Royal Statistical Society award </span></a>
</h2>
<ul class="ons-document-list__item-metadata ons-u-mb-xs">
<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-xs">
<a href="#0">Five Office for National Statistics names in New Year’s Honours </span></a>
</h2>
<ul class="ons-document-list__item-metadata ons-u-mb-xs">
<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.
{% 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'
},
"url": '#0',
"title": 'Landmarks are lighting up purple to mark Census Day',
"metadata": {
"type": {
"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
Name
Type
Required
Description
id
string
false
The HTML id attribute for the document list element
classes
string
false
Classes for the document list element
attributes
object
false
HTML attributes (for example, data attributes) to add to the document list element
Label for the type of document, for example “User requested data”.
url
string
false
URL href for the type. Can be used to filter a list of documents by category.
ref
string
false
Text for a sub-type or reference. Can be used to give extra detail about the type, for example, “User requested data: Ref 008052”.
Date
Name
Type
Required
Description
iso
string
true
ISO format meachine-readable date, for example, 2020-05-20
short
string
true
Displayed short format of the date, for example, “20 May 2020”
prefix
string
false
Label to prefix the date for context, for example, “Last updated” (Defaults to “Published”). Is automatically suffixed with a colon.
showPrefix
boolean
false
Displays the prefix when set to true. Otherwise it will be hidden. Use when context is required.
File
Name
Type
Required
Description
fileType
string
true
Format of the file, for example, PDF, DOC, XLS
fileSize
string
true
Size of the file in megabytes or kilobytes, for example, “850KB”
filePages
string
false
Number of pages in the file, for example, “16 pages”
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-xs">
<a href="#0">Landmarks are lighting up purple to mark Census Day </span></a>
</h2>
<ul class="ons-document-list__item-metadata ons-u-mb-xs">
<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: