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
| 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 |
| documents | Array<Document> | true | An array of document items in the documents list |
| headingLevel | int | false | Number 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 |
| Name | Type | Required | Description |
|---|---|---|---|
| classes | string | false | Custom classes to add to each document list item |
| attributes | object | false | HTML attributes (for example, data attributes) to add to each document list item |
| title | Object<Title> | true | An object containing text and url of the title |
| description | string | false | A short HTML extract of text (for example, a short sentence to give some context of the document) |
| thumbnail | Object<Thumbnail> | false | An object containing path and filename attributes for the thumbnail image. Renders a placeholder instead if set to true |
| metadata | Object<Metadata> | false | An object for a list of information about document, for example, date, type and size |
| featured | boolean | false | Will render a featured variant of the document if set to true |
| fullWidth | boolean | false | If 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. |
| wide | boolean | false | Set to true to increase the maximum width of the layout container to 1280px. |
| showMetadataFirst | boolean | false | If set to true, metadata is displayed above the header. |
| Name | Type | Required | Description |
|---|---|---|---|
| smallSrc | string | true | Path to the non-retina version of the image |
| largeSrc | string | true | Path to the retina version of the image |
| Name | Type | Required | Description |
|---|---|---|---|
| object | Object<Object> | false | An object for a list item describing the type of document, for example, “Dataset” or “Press release” |
| date | Object<Date> | false | An object for the date the document was published or updated |
| file | Object<File> | false | An object to describe the details of the downloadable file such as format and size |
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | true | 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”. |
| Name | Type | Required | Description |
|---|---|---|---|
| iso | string | true | ISO format machine-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. |
| 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” |
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | true | The title for the document |
| url | string | true | The 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
| 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 |
| documents | Array<Document> | true | An array of document items in the documents list |
| headingLevel | int | false | Number 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 |
| Name | Type | Required | Description |
|---|---|---|---|
| classes | string | false | Custom classes to add to each document list item |
| attributes | object | false | HTML attributes (for example, data attributes) to add to each document list item |
| title | Object<Title> | true | An object containing text and url of the title |
| description | string | false | A short HTML extract of text (for example, a short sentence to give some context of the document) |
| thumbnail | Object<Thumbnail> | false | An object containing path and filename attributes for the thumbnail image. Renders a placeholder instead if set to true |
| metadata | Object<Metadata> | false | An object for a list of information about document, for example, date, type and size |
| featured | boolean | false | Will render a featured variant of the document if set to true |
| fullWidth | boolean | false | If 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. |
| wide | boolean | false | Set to true to increase the maximum width of the layout container to 1280px. |
| showMetadataFirst | boolean | false | If set to true, metadata is displayed above the header. |
| Name | Type | Required | Description |
|---|---|---|---|
| smallSrc | string | true | Path to the non-retina version of the image |
| largeSrc | string | true | Path to the retina version of the image |
| Name | Type | Required | Description |
|---|---|---|---|
| object | Object<Object> | false | An object for a list item describing the type of document, for example, “Dataset” or “Press release” |
| date | Object<Date> | false | An object for the date the document was published or updated |
| file | Object<File> | false | An object to describe the details of the downloadable file such as format and size |
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | true | 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”. |
| Name | Type | Required | Description |
|---|---|---|---|
| iso | string | true | ISO format machine-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. |
| 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” |
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | true | The title for the document |
| url | string | true | The 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>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.
Example Document List Search Result Featured 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 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 |
| documents | Array<Document> | true | An array of document items in the documents list |
| headingLevel | int | false | Number 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 |
| Name | Type | Required | Description |
|---|---|---|---|
| classes | string | false | Custom classes to add to each document list item |
| attributes | object | false | HTML attributes (for example, data attributes) to add to each document list item |
| title | Object<Title> | true | An object containing text and url of the title |
| description | string | false | A short HTML extract of text (for example, a short sentence to give some context of the document) |
| thumbnail | Object<Thumbnail> | false | An object containing path and filename attributes for the thumbnail image. Renders a placeholder instead if set to true |
| metadata | Object<Metadata> | false | An object for a list of information about document, for example, date, type and size |
| featured | boolean | false | Will render a featured variant of the document if set to true |
| fullWidth | boolean | false | If 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. |
| wide | boolean | false | Set to true to increase the maximum width of the layout container to 1280px. |
| showMetadataFirst | boolean | false | If set to true, metadata is displayed above the header. |
| Name | Type | Required | Description |
|---|---|---|---|
| smallSrc | string | true | Path to the non-retina version of the image |
| largeSrc | string | true | Path to the retina version of the image |
| Name | Type | Required | Description |
|---|---|---|---|
| object | Object<Object> | false | An object for a list item describing the type of document, for example, “Dataset” or “Press release” |
| date | Object<Date> | false | An object for the date the document was published or updated |
| file | Object<File> | false | An object to describe the details of the downloadable file such as format and size |
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | true | 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”. |
| Name | Type | Required | Description |
|---|---|---|---|
| iso | string | true | ISO format machine-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. |
| 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” |
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | true | The title for the document |
| url | string | true | The 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 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.
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
| 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 |
| documents | Array<Document> | true | An array of document items in the documents list |
| headingLevel | int | false | Number 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 |
| Name | Type | Required | Description |
|---|---|---|---|
| classes | string | false | Custom classes to add to each document list item |
| attributes | object | false | HTML attributes (for example, data attributes) to add to each document list item |
| title | Object<Title> | true | An object containing text and url of the title |
| description | string | false | A short HTML extract of text (for example, a short sentence to give some context of the document) |
| thumbnail | Object<Thumbnail> | false | An object containing path and filename attributes for the thumbnail image. Renders a placeholder instead if set to true |
| metadata | Object<Metadata> | false | An object for a list of information about document, for example, date, type and size |
| featured | boolean | false | Will render a featured variant of the document if set to true |
| fullWidth | boolean | false | If 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. |
| wide | boolean | false | Set to true to increase the maximum width of the layout container to 1280px. |
| showMetadataFirst | boolean | false | If set to true, metadata is displayed above the header. |
| Name | Type | Required | Description |
|---|---|---|---|
| smallSrc | string | true | Path to the non-retina version of the image |
| largeSrc | string | true | Path to the retina version of the image |
| Name | Type | Required | Description |
|---|---|---|---|
| object | Object<Object> | false | An object for a list item describing the type of document, for example, “Dataset” or “Press release” |
| date | Object<Date> | false | An object for the date the document was published or updated |
| file | Object<File> | false | An object to describe the details of the downloadable file such as format and size |
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | true | 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”. |
| Name | Type | Required | Description |
|---|---|---|---|
| iso | string | true | ISO format machine-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. |
| 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” |
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | true | The title for the document |
| url | string | true | The 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
| 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 |
| documents | Array<Document> | true | An array of document items in the documents list |
| headingLevel | int | false | Number 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 |
| Name | Type | Required | Description |
|---|---|---|---|
| classes | string | false | Custom classes to add to each document list item |
| attributes | object | false | HTML attributes (for example, data attributes) to add to each document list item |
| title | Object<Title> | true | An object containing text and url of the title |
| description | string | false | A short HTML extract of text (for example, a short sentence to give some context of the document) |
| thumbnail | Object<Thumbnail> | false | An object containing path and filename attributes for the thumbnail image. Renders a placeholder instead if set to true |
| metadata | Object<Metadata> | false | An object for a list of information about document, for example, date, type and size |
| featured | boolean | false | Will render a featured variant of the document if set to true |
| fullWidth | boolean | false | If 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. |
| wide | boolean | false | Set to true to increase the maximum width of the layout container to 1280px. |
| showMetadataFirst | boolean | false | If set to true, metadata is displayed above the header. |
| Name | Type | Required | Description |
|---|---|---|---|
| smallSrc | string | true | Path to the non-retina version of the image |
| largeSrc | string | true | Path to the retina version of the image |
| Name | Type | Required | Description |
|---|---|---|---|
| object | Object<Object> | false | An object for a list item describing the type of document, for example, “Dataset” or “Press release” |
| date | Object<Date> | false | An object for the date the document was published or updated |
| file | Object<File> | false | An object to describe the details of the downloadable file such as format and size |
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | true | 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”. |
| Name | Type | Required | Description |
|---|---|---|---|
| iso | string | true | ISO format machine-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. |
| 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” |
| Name | Type | Required | Description |
|---|---|---|---|
| text | string | true | The title for the document |
| url | string | true | The 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)