Skip to main content

User testing

Help us improve this service. Take part in a short online exercise

Document list

Experimental

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.

When a large quantity of files are available to download, use the download resources pattern.

Warning:
Always use HTML web pages to publish documents where possible. Any downloadable document must meet accessibility standards such as those described in the brand guidance for PDFs
<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" href="/patternlib-img/download-resources/documents/Print-Ready-A4EB1-2021-v1-0-120620.pdf" tabindex="-1">
        <img srcset="/patternlib-img/download-resources/img/small/including-everyone-in-census-2021-v2.png 1x, /patternlib-img/download-resources/img/large/including-everyone-in-census-2021-v2.png 2x" src="/patternlib-img/download-resources/img/small/including-everyone-in-census-2021-v2.png" 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="/patternlib-img/download-resources/documents/Print-Ready-A4EB1-2021-v1-0-120620.pdf">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-xs">
          <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" href="/patternlib-img/download-resources/documents/CHDE1-Community-Handbook-v0.6.pdf" tabindex="-1">
        <img srcset="/patternlib-img/download-resources/img/small/including-everyone-in-census-2021.png 1x, /patternlib-img/download-resources/img/large/including-everyone-in-census-2021.png 2x" src="/patternlib-img/download-resources/img/small/including-everyone-in-census-2021.png" 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="/patternlib-img/download-resources/documents/CHDE1-Community-Handbook-v0.6.pdf">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-xs">
          <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="/patternlib-img/download-resources/documents/Print-Ready-A4GIP1-2021-v1-0-120620.pdf" 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="/patternlib-img/download-resources/documents/Print-Ready-A4GIP1-2021-v1-0-120620.pdf">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-xs">
          <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>
{% from "components/document-list/_macro.njk" import onsDocumentList %}
{{ onsDocumentList({
    "documents": [
        {
            "thumbnail": {
                "smallSrc": '/patternlib-img/download-resources/img/small/including-everyone-in-census-2021-v2.png',
                "largeSrc": '/patternlib-img/download-resources/img/large/including-everyone-in-census-2021-v2.png'
            },
            "url": '/patternlib-img/download-resources/documents/Print-Ready-A4EB1-2021-v1-0-120620.pdf',            
            "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": {
                "smallSrc": '/patternlib-img/download-resources/img/small/including-everyone-in-census-2021.png',
                "largeSrc": '/patternlib-img/download-resources/img/large/including-everyone-in-census-2021.png'
            },
            "url": '/patternlib-img/download-resources/documents/CHDE1-Community-Handbook-v0.6.pdf',
            "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": '/patternlib-img/download-resources/documents/Print-Ready-A4GIP1-2021-v1-0-120620.pdf',
            "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.'
        }
    ]
}) }}
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
titleTag string false The HTML heading tag to wrap each document list item’s title to make sure the headings have the correct semantic order on the page. Defaults to h2

Document

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 string true The title for the document
url string true The URL for the document link (either a file or web page)
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
wide boolean false Set to true to increase the maximum width of the layout container to 1280px.

Thumbnail

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

Metadata

Name Type Required Description
type <Object>Type 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

Type

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”.

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”
{% macro onsDocumentList(params) %}
    <ul{% if params.id is defined and params.id %} id="{{ params.id }}"{% endif %} class="ons-document-list{{ ' ' + params.classes if params.classes is defined and params.classes else '' }}"{% if params.attributes is defined and params.attributes %}{% for attribute, value in (params.attributes.items() if params.attributes is mapping and params.attributes.items else params.attributes) %} {{attribute}}="{{value}}"{% endfor %}{% endif %}>
        {% for document in (params.documents if params.documents is iterable else params.documents.items()) %}

        <li class="ons-document-list__item{{ ' ons-document-list__item--featured' if document.featured is defined and document.featured }}{{ ' ons-document-list__item--full-width' if document.fullWidth is defined and document.fullWidth == true }}{{ ' ' + document.classes if document.classes is defined and document.classes else '' }}"{% if document.attributes is defined and document.attributes %}{% for attribute, value in (document.attributes.items() if document.attributes is mapping and document.attributes.items else document.attributes) %} {{attribute}}="{{value}}"{% endfor %}{% endif %}>

            {% if document.fullWidth is defined and document.fullWidth == true %}

                <div class="ons-container{{ ' ons-container--wide' if document.wide is defined and document.wide == true }}">

            {% endif %}

                    {% if document.thumbnail is defined or document.thumbnail == true %}

                        <div class="ons-document-list__item-image{%- if document.metadata.file is defined and document.metadata.file %} ons-document-list__item-image--file{% endif %}" aria-hidden="true">
                            <a class="ons-document-list__image-link{{ ' ons-document-list__image-link--placeholder' if not document.thumbnail.smallSrc }}" href="{{ document.url }}" tabindex="-1">
                                {% if document.thumbnail.smallSrc is defined and document.thumbnail.smallSrc and document.thumbnail.largeSrc is defined and document.thumbnail.largeSrc %}
                                    <img srcset="{{ document.thumbnail.smallSrc }} 1x, {{ document.thumbnail.largeSrc }} 2x" src="{{ document.thumbnail.smallSrc }}" alt="" loading="lazy">
                                {% endif %}
                            </a>
                        </div>

                    {% endif %}

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

                        <div class="ons-document-list__item-header{{ ' ons-document-list__item-header--reverse' if document.showMetadataFirst is defined and document.showMetadataFirst == true }}">

                            {% set titleTag = params.titleTag | default("h2") %}

                            <{{ titleTag }} class="ons-document-list__item-title ons-u-fs-m ons-u-mt-no ons-u-mb-xs">
                                <a href="{{ document.url }}">{{ document.title }}
                                {%- if document.metadata is defined and document.metadata and document.metadata.file is defined and document.metadata.file %}
                                <span class="ons-u-vh">
                                    {% set fileMetadataItems = [] %}
                                    {% if document.metadata.file.fileType is defined and document.metadata.file.fileType %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileType + ' document download'), fileMetadataItems) %}{% endif %}
                                    {% if document.metadata.file.fileSize is defined and document.metadata.file.fileSize %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileSize), fileMetadataItems) %}{% endif %}
                                    {% if document.metadata.file.filePages is defined and document.metadata.file.filePages %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.filePages), fileMetadataItems) %}{% endif %}

                                    , {{ fileMetadataItems | join(', ') }}

                                {% endif %}

                                </span></a>
                            </{{ titleTag }}>

                            {%- if document.metadata is defined and document.metadata %}

                                <ul class="ons-document-list__item-metadata{% if document.description is defined and document.description %} ons-u-mb-xs{% else %} ons-u-mb-no{% endif %}">

                                    {%- if document.metadata.date is defined and document.metadata.date %}
                                        <li class="ons-document-list__item-attribute">
                                            {% if document.metadata.date -%}
                                                {% set prefixClasses = "ons-u-fw-b" if document.metadata.date.showPrefix is defined and document.metadata.date.showPrefix == true else "ons-u-vh" %}
                                                <span class="{{ prefixClasses }}">{{ document.metadata.date.prefix | default("Published") }}: </span>
                                            {%- endif -%}
                                            {% if document.metadata.date.iso is defined and document.metadata.date.iso -%}
                                                <time datetime="{{ document.metadata.date.iso }}">{{ document.metadata.date.short }}</time>
                                            {%- endif %}
                                        </li>
                                    {% endif %}

                                    {%- if document.metadata.type is defined and document.metadata.type and document.metadata.type.text is defined and document.metadata.type.text %}
                                        <li class="ons-document-list__item-attribute{%- if document.metadata.file is defined and document.metadata.file %} ons-u-mr-no{% endif %}">
                                            {%- if document.metadata.type.url is defined and document.metadata.type.url %}
                                                <a class="ons-document-list__attribute-link" href="{{ document.metadata.type.url }}">
                                            {% endif %}
                                                    <span {% if not document.metadata.file and not document.metadata.type.url %}class="ons-u-fw-b"{% endif %}>{{ document.metadata.type.text }}{%- if document.metadata.type.ref is defined and document.metadata.type.ref %}: {% elif document.metadata.file is defined and document.metadata.file %},{% endif %}</span>
                                            {%- if document.metadata.type.url is defined and document.metadata.type.url %}
                                                </a>
                                            {% endif %}
                                            {%- if document.metadata.type.ref is defined and document.metadata.type.ref %}
                                                <span>{{ document.metadata.type.ref }}</span>
                                            {% endif %}
                                        </li>
                                    {% endif %}

                                    {%- if document.metadata.file is defined and document.metadata.file and document.metadata.file.fileType is defined and document.metadata.file.fileType %}

                                        <li class="ons-document-list__item-attribute" aria-hidden="true">
                                            {% set fileMetadataItems = [] %}

                                            {% if document.metadata.file.fileType is defined and document.metadata.file.fileType %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileType), fileMetadataItems) %}{% endif %}
                                            {% if document.metadata.file.fileSize is defined and document.metadata.file.fileSize %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileSize), fileMetadataItems) %}{% endif %}
                                            {% if document.metadata.file.filePages is defined and document.metadata.file.filePages %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.filePages), fileMetadataItems) %}{% endif %}

                                            {{ fileMetadataItems | join(', ') }}
                                        </li>

                                    {% endif -%}
                                </ul>

                            {% endif %}
                        </div>

                        {% if document.description is defined and document.description %}
                            <div class="ons-document-list__item-description">{{ document.description | safe }}</div>
                        {% endif %}

                    </div>

            {% if document.fullWidth is defined and document.fullWidth == true %}

                </div>

            {% endif %}

        </li>
        {% endfor %}
    </ul>

{% endmacro %}
.ons-document-list {
  @extend .ons-list--bare;

  margin-bottom: 0;

  &__item {
    border-bottom: 1px solid $color-borders-list;
    margin: 0 0 1.5rem;
    padding: 0 0 1.5rem;

    @include mq(xs) {
      align-items: flex-start;
      display: flex;
    }

    &:last-of-type {
      border-bottom: 0;
      margin: 0;
    }
  }

  &__item-image {
    flex: 0 0 auto;
    margin-bottom: 1rem;
    width: 136px;

    @include mq(xs) {
      margin-right: 1.5rem;
    }

    @include mq(m) {
      margin-bottom: 0;
    }
  }

  &__item-image & {
    &__image-link {
      &--placeholder {
        height: 96px;
      }
    }
  }

  &__item-image--file {
    width: 96px;
  }

  &__item-image--file & {
    &__image-link {
      border-color: $color-borders-document-image;

      &--placeholder {
        height: 136px;
      }
    }
  }

  &__image-link {
    border: 2px solid transparent;
    box-sizing: content-box;
    display: block;
    width: 100%;

    &:focus {
      background-color: $color-placeholder !important;
      border: 2px solid $color-borders-document-image-focus;
      box-shadow: none;
      outline: 4px solid $color-focus !important;
      outline-offset: 0;
    }

    &--placeholder {
      background-clip: padding-box;
      background-color: $color-borders-document-image;
      background-image: url("data:image/svg+xml;charset=UTF-8,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3e%3cpath fill='%23fff' d='M0 19.39c.49-1 1-2 1.55-2.93A31.59 31.59 0 0 1 0 11.72v7.67ZM3 0S0 0 0 3.7v2a34.85 34.85 0 0 0 2.17 9.76A31.2 31.2 0 0 1 8.3 8.3c4.84-4.16 11.36-7 20.21-8.29Zm28.84 2c-10.11 1-17 3.86-22 8.1a29.78 29.78 0 0 0-6.49 8C7.26 25.65 14.66 31.19 27 32h1.21A3.71 3.71 0 0 0 32 27.91V2a.41.41 0 0 1-.16 0Zm-26 21.49a25.94 25.94 0 0 1-3-4.4A48 48 0 0 0 0 25.71V32h20.23a26.41 26.41 0 0 1-14.39-8.49Z'/%3e%3c/svg%3e");
      background-position: center;
      background-repeat: no-repeat;
      background-size: 32px 32px;
      height: 100%;
    }
  }

  &__item-metadata {
    @extend .ons-list--bare;

    line-height: 1.2 !important;
  }

  &__item-attribute {
    color: $color-text-metadata;
    display: inline-block;
    margin: 0 1rem 0 0;

    @extend .ons-u-fs-s;
  }

  &__attribute-link {
    color: inherit;

    &:hover {
      color: $color-text-metadata;
      text-decoration: underline solid $color-text-metadata 2px;
    }
  }

  &__item-description {
    margin-bottom: 0;
    max-width: 660px; // Equivalent to 8 Columns

    p:last-of-type {
      margin-bottom: 0;
    }
  }
}

// Featured document
.ons-document-list {
  &__item {
    &--featured {
      background-color: $color-banner-bg;
      border-bottom: none;
      display: block;
      padding: 2rem;

      @include mq(m) {
        align-items: flex-start;
        display: flex;

        .ons-container {
          display: flex;
        }
      }

      // Increase thumbnail image size
      .ons-document-list__item-image {
        width: 248px;

        & &__image-link {
          &--placeholder {
            height: 96px;
          }
        }

        @include mq(m) {
          margin-right: 2.5rem;
          width: 379px;

          & &__image-link {
            &--placeholder {
              height: 248px;
            }
          }
        }
      }

      // Show metadata above title
      .ons-document-list__item-header {
        &--reverse {
          display: flex;
          flex-direction: column-reverse;
          margin-bottom: 0.5rem;
        }
      }

      // Increase font size
      .ons-document-list__item-title {
        @extend .ons-u-fs-l;
      }

      // If featured item is first in same list
      & + .ons-document-list__item {
        border-top: none;
        margin-top: 0;
      }
    }

    // If featured item is full width
    &--full-width {
      padding: 2rem 0;
    }
  }
}

Search results

Use this variant to build an index of search results.

<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 <em class="ons-highlight">crime</em> levels and trends for England and Wales based primarily on two sets of statistics: the <em class="ons-highlight">Crime</em> Survey for England and Wales (CSEW) and police recorded <em class="ons-highlight">crime</em> 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 <em class="ons-highlight">Crime</em> 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 <em class="ons-highlight">crime</em> 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>
{% 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 <em class="ons-highlight">crime</em> levels and trends for England and Wales based primarily on two sets of statistics: the <em class="ons-highlight">Crime</em> Survey for England and Wales (CSEW) and police recorded <em class="ons-highlight">crime</em> 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 <em class="ons-highlight">Crime</em> 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 <em class="ons-highlight">crime</em> 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'
                }
            }
        }
    ]
}) }}
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
titleTag string false The HTML heading tag to wrap each document list item’s title to make sure the headings have the correct semantic order on the page. Defaults to h2

Document

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 string true The title for the document
url string true The URL for the document link (either a file or web page)
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
wide boolean false Set to true to increase the maximum width of the layout container to 1280px.

Thumbnail

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

Metadata

Name Type Required Description
type <Object>Type 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

Type

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”.

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”
{% macro onsDocumentList(params) %}
    <ul{% if params.id is defined and params.id %} id="{{ params.id }}"{% endif %} class="ons-document-list{{ ' ' + params.classes if params.classes is defined and params.classes else '' }}"{% if params.attributes is defined and params.attributes %}{% for attribute, value in (params.attributes.items() if params.attributes is mapping and params.attributes.items else params.attributes) %} {{attribute}}="{{value}}"{% endfor %}{% endif %}>
        {% for document in (params.documents if params.documents is iterable else params.documents.items()) %}

        <li class="ons-document-list__item{{ ' ons-document-list__item--featured' if document.featured is defined and document.featured }}{{ ' ons-document-list__item--full-width' if document.fullWidth is defined and document.fullWidth == true }}{{ ' ' + document.classes if document.classes is defined and document.classes else '' }}"{% if document.attributes is defined and document.attributes %}{% for attribute, value in (document.attributes.items() if document.attributes is mapping and document.attributes.items else document.attributes) %} {{attribute}}="{{value}}"{% endfor %}{% endif %}>

            {% if document.fullWidth is defined and document.fullWidth == true %}

                <div class="ons-container{{ ' ons-container--wide' if document.wide is defined and document.wide == true }}">

            {% endif %}

                    {% if document.thumbnail is defined or document.thumbnail == true %}

                        <div class="ons-document-list__item-image{%- if document.metadata.file is defined and document.metadata.file %} ons-document-list__item-image--file{% endif %}" aria-hidden="true">
                            <a class="ons-document-list__image-link{{ ' ons-document-list__image-link--placeholder' if not document.thumbnail.smallSrc }}" href="{{ document.url }}" tabindex="-1">
                                {% if document.thumbnail.smallSrc is defined and document.thumbnail.smallSrc and document.thumbnail.largeSrc is defined and document.thumbnail.largeSrc %}
                                    <img srcset="{{ document.thumbnail.smallSrc }} 1x, {{ document.thumbnail.largeSrc }} 2x" src="{{ document.thumbnail.smallSrc }}" alt="" loading="lazy">
                                {% endif %}
                            </a>
                        </div>

                    {% endif %}

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

                        <div class="ons-document-list__item-header{{ ' ons-document-list__item-header--reverse' if document.showMetadataFirst is defined and document.showMetadataFirst == true }}">

                            {% set titleTag = params.titleTag | default("h2") %}

                            <{{ titleTag }} class="ons-document-list__item-title ons-u-fs-m ons-u-mt-no ons-u-mb-xs">
                                <a href="{{ document.url }}">{{ document.title }}
                                {%- if document.metadata is defined and document.metadata and document.metadata.file is defined and document.metadata.file %}
                                <span class="ons-u-vh">
                                    {% set fileMetadataItems = [] %}
                                    {% if document.metadata.file.fileType is defined and document.metadata.file.fileType %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileType + ' document download'), fileMetadataItems) %}{% endif %}
                                    {% if document.metadata.file.fileSize is defined and document.metadata.file.fileSize %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileSize), fileMetadataItems) %}{% endif %}
                                    {% if document.metadata.file.filePages is defined and document.metadata.file.filePages %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.filePages), fileMetadataItems) %}{% endif %}

                                    , {{ fileMetadataItems | join(', ') }}

                                {% endif %}

                                </span></a>
                            </{{ titleTag }}>

                            {%- if document.metadata is defined and document.metadata %}

                                <ul class="ons-document-list__item-metadata{% if document.description is defined and document.description %} ons-u-mb-xs{% else %} ons-u-mb-no{% endif %}">

                                    {%- if document.metadata.date is defined and document.metadata.date %}
                                        <li class="ons-document-list__item-attribute">
                                            {% if document.metadata.date -%}
                                                {% set prefixClasses = "ons-u-fw-b" if document.metadata.date.showPrefix is defined and document.metadata.date.showPrefix == true else "ons-u-vh" %}
                                                <span class="{{ prefixClasses }}">{{ document.metadata.date.prefix | default("Published") }}: </span>
                                            {%- endif -%}
                                            {% if document.metadata.date.iso is defined and document.metadata.date.iso -%}
                                                <time datetime="{{ document.metadata.date.iso }}">{{ document.metadata.date.short }}</time>
                                            {%- endif %}
                                        </li>
                                    {% endif %}

                                    {%- if document.metadata.type is defined and document.metadata.type and document.metadata.type.text is defined and document.metadata.type.text %}
                                        <li class="ons-document-list__item-attribute{%- if document.metadata.file is defined and document.metadata.file %} ons-u-mr-no{% endif %}">
                                            {%- if document.metadata.type.url is defined and document.metadata.type.url %}
                                                <a class="ons-document-list__attribute-link" href="{{ document.metadata.type.url }}">
                                            {% endif %}
                                                    <span {% if not document.metadata.file and not document.metadata.type.url %}class="ons-u-fw-b"{% endif %}>{{ document.metadata.type.text }}{%- if document.metadata.type.ref is defined and document.metadata.type.ref %}: {% elif document.metadata.file is defined and document.metadata.file %},{% endif %}</span>
                                            {%- if document.metadata.type.url is defined and document.metadata.type.url %}
                                                </a>
                                            {% endif %}
                                            {%- if document.metadata.type.ref is defined and document.metadata.type.ref %}
                                                <span>{{ document.metadata.type.ref }}</span>
                                            {% endif %}
                                        </li>
                                    {% endif %}

                                    {%- if document.metadata.file is defined and document.metadata.file and document.metadata.file.fileType is defined and document.metadata.file.fileType %}

                                        <li class="ons-document-list__item-attribute" aria-hidden="true">
                                            {% set fileMetadataItems = [] %}

                                            {% if document.metadata.file.fileType is defined and document.metadata.file.fileType %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileType), fileMetadataItems) %}{% endif %}
                                            {% if document.metadata.file.fileSize is defined and document.metadata.file.fileSize %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileSize), fileMetadataItems) %}{% endif %}
                                            {% if document.metadata.file.filePages is defined and document.metadata.file.filePages %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.filePages), fileMetadataItems) %}{% endif %}

                                            {{ fileMetadataItems | join(', ') }}
                                        </li>

                                    {% endif -%}
                                </ul>

                            {% endif %}
                        </div>

                        {% if document.description is defined and document.description %}
                            <div class="ons-document-list__item-description">{{ document.description | safe }}</div>
                        {% endif %}

                    </div>

            {% if document.fullWidth is defined and document.fullWidth == true %}

                </div>

            {% endif %}

        </li>
        {% endfor %}
    </ul>

{% endmacro %}
.ons-document-list {
  @extend .ons-list--bare;

  margin-bottom: 0;

  &__item {
    border-bottom: 1px solid $color-borders-list;
    margin: 0 0 1.5rem;
    padding: 0 0 1.5rem;

    @include mq(xs) {
      align-items: flex-start;
      display: flex;
    }

    &:last-of-type {
      border-bottom: 0;
      margin: 0;
    }
  }

  &__item-image {
    flex: 0 0 auto;
    margin-bottom: 1rem;
    width: 136px;

    @include mq(xs) {
      margin-right: 1.5rem;
    }

    @include mq(m) {
      margin-bottom: 0;
    }
  }

  &__item-image & {
    &__image-link {
      &--placeholder {
        height: 96px;
      }
    }
  }

  &__item-image--file {
    width: 96px;
  }

  &__item-image--file & {
    &__image-link {
      border-color: $color-borders-document-image;

      &--placeholder {
        height: 136px;
      }
    }
  }

  &__image-link {
    border: 2px solid transparent;
    box-sizing: content-box;
    display: block;
    width: 100%;

    &:focus {
      background-color: $color-placeholder !important;
      border: 2px solid $color-borders-document-image-focus;
      box-shadow: none;
      outline: 4px solid $color-focus !important;
      outline-offset: 0;
    }

    &--placeholder {
      background-clip: padding-box;
      background-color: $color-borders-document-image;
      background-image: url("data:image/svg+xml;charset=UTF-8,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3e%3cpath fill='%23fff' d='M0 19.39c.49-1 1-2 1.55-2.93A31.59 31.59 0 0 1 0 11.72v7.67ZM3 0S0 0 0 3.7v2a34.85 34.85 0 0 0 2.17 9.76A31.2 31.2 0 0 1 8.3 8.3c4.84-4.16 11.36-7 20.21-8.29Zm28.84 2c-10.11 1-17 3.86-22 8.1a29.78 29.78 0 0 0-6.49 8C7.26 25.65 14.66 31.19 27 32h1.21A3.71 3.71 0 0 0 32 27.91V2a.41.41 0 0 1-.16 0Zm-26 21.49a25.94 25.94 0 0 1-3-4.4A48 48 0 0 0 0 25.71V32h20.23a26.41 26.41 0 0 1-14.39-8.49Z'/%3e%3c/svg%3e");
      background-position: center;
      background-repeat: no-repeat;
      background-size: 32px 32px;
      height: 100%;
    }
  }

  &__item-metadata {
    @extend .ons-list--bare;

    line-height: 1.2 !important;
  }

  &__item-attribute {
    color: $color-text-metadata;
    display: inline-block;
    margin: 0 1rem 0 0;

    @extend .ons-u-fs-s;
  }

  &__attribute-link {
    color: inherit;

    &:hover {
      color: $color-text-metadata;
      text-decoration: underline solid $color-text-metadata 2px;
    }
  }

  &__item-description {
    margin-bottom: 0;
    max-width: 660px; // Equivalent to 8 Columns

    p:last-of-type {
      margin-bottom: 0;
    }
  }
}

// Featured document
.ons-document-list {
  &__item {
    &--featured {
      background-color: $color-banner-bg;
      border-bottom: none;
      display: block;
      padding: 2rem;

      @include mq(m) {
        align-items: flex-start;
        display: flex;

        .ons-container {
          display: flex;
        }
      }

      // Increase thumbnail image size
      .ons-document-list__item-image {
        width: 248px;

        & &__image-link {
          &--placeholder {
            height: 96px;
          }
        }

        @include mq(m) {
          margin-right: 2.5rem;
          width: 379px;

          & &__image-link {
            &--placeholder {
              height: 248px;
            }
          }
        }
      }

      // Show metadata above title
      .ons-document-list__item-header {
        &--reverse {
          display: flex;
          flex-direction: column-reverse;
          margin-bottom: 0.5rem;
        }
      }

      // Increase font size
      .ons-document-list__item-title {
        @extend .ons-u-fs-l;
      }

      // If featured item is first in same list
      & + .ons-document-list__item {
        border-top: none;
        margin-top: 0;
      }
    }

    // If featured item is full width
    &--full-width {
      padding: 2rem 0;
    }
  }
}

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.

<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 <em class="ons-highlight">crime</em> levels and trends for England and Wales based primarily on two sets of statistics: the <em class="ons-highlight">Crime</em> 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>
{% 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 <em class="ons-highlight">crime</em> levels and trends for England and Wales based primarily on two sets of statistics: the <em class="ons-highlight">Crime</em> 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>'
        }
    ]
}) }}
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
titleTag string false The HTML heading tag to wrap each document list item’s title to make sure the headings have the correct semantic order on the page. Defaults to h2

Document

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 string true The title for the document
url string true The URL for the document link (either a file or web page)
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
wide boolean false Set to true to increase the maximum width of the layout container to 1280px.

Thumbnail

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

Metadata

Name Type Required Description
type <Object>Type 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

Type

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”.

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”
{% macro onsDocumentList(params) %}
    <ul{% if params.id is defined and params.id %} id="{{ params.id }}"{% endif %} class="ons-document-list{{ ' ' + params.classes if params.classes is defined and params.classes else '' }}"{% if params.attributes is defined and params.attributes %}{% for attribute, value in (params.attributes.items() if params.attributes is mapping and params.attributes.items else params.attributes) %} {{attribute}}="{{value}}"{% endfor %}{% endif %}>
        {% for document in (params.documents if params.documents is iterable else params.documents.items()) %}

        <li class="ons-document-list__item{{ ' ons-document-list__item--featured' if document.featured is defined and document.featured }}{{ ' ons-document-list__item--full-width' if document.fullWidth is defined and document.fullWidth == true }}{{ ' ' + document.classes if document.classes is defined and document.classes else '' }}"{% if document.attributes is defined and document.attributes %}{% for attribute, value in (document.attributes.items() if document.attributes is mapping and document.attributes.items else document.attributes) %} {{attribute}}="{{value}}"{% endfor %}{% endif %}>

            {% if document.fullWidth is defined and document.fullWidth == true %}

                <div class="ons-container{{ ' ons-container--wide' if document.wide is defined and document.wide == true }}">

            {% endif %}

                    {% if document.thumbnail is defined or document.thumbnail == true %}

                        <div class="ons-document-list__item-image{%- if document.metadata.file is defined and document.metadata.file %} ons-document-list__item-image--file{% endif %}" aria-hidden="true">
                            <a class="ons-document-list__image-link{{ ' ons-document-list__image-link--placeholder' if not document.thumbnail.smallSrc }}" href="{{ document.url }}" tabindex="-1">
                                {% if document.thumbnail.smallSrc is defined and document.thumbnail.smallSrc and document.thumbnail.largeSrc is defined and document.thumbnail.largeSrc %}
                                    <img srcset="{{ document.thumbnail.smallSrc }} 1x, {{ document.thumbnail.largeSrc }} 2x" src="{{ document.thumbnail.smallSrc }}" alt="" loading="lazy">
                                {% endif %}
                            </a>
                        </div>

                    {% endif %}

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

                        <div class="ons-document-list__item-header{{ ' ons-document-list__item-header--reverse' if document.showMetadataFirst is defined and document.showMetadataFirst == true }}">

                            {% set titleTag = params.titleTag | default("h2") %}

                            <{{ titleTag }} class="ons-document-list__item-title ons-u-fs-m ons-u-mt-no ons-u-mb-xs">
                                <a href="{{ document.url }}">{{ document.title }}
                                {%- if document.metadata is defined and document.metadata and document.metadata.file is defined and document.metadata.file %}
                                <span class="ons-u-vh">
                                    {% set fileMetadataItems = [] %}
                                    {% if document.metadata.file.fileType is defined and document.metadata.file.fileType %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileType + ' document download'), fileMetadataItems) %}{% endif %}
                                    {% if document.metadata.file.fileSize is defined and document.metadata.file.fileSize %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileSize), fileMetadataItems) %}{% endif %}
                                    {% if document.metadata.file.filePages is defined and document.metadata.file.filePages %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.filePages), fileMetadataItems) %}{% endif %}

                                    , {{ fileMetadataItems | join(', ') }}

                                {% endif %}

                                </span></a>
                            </{{ titleTag }}>

                            {%- if document.metadata is defined and document.metadata %}

                                <ul class="ons-document-list__item-metadata{% if document.description is defined and document.description %} ons-u-mb-xs{% else %} ons-u-mb-no{% endif %}">

                                    {%- if document.metadata.date is defined and document.metadata.date %}
                                        <li class="ons-document-list__item-attribute">
                                            {% if document.metadata.date -%}
                                                {% set prefixClasses = "ons-u-fw-b" if document.metadata.date.showPrefix is defined and document.metadata.date.showPrefix == true else "ons-u-vh" %}
                                                <span class="{{ prefixClasses }}">{{ document.metadata.date.prefix | default("Published") }}: </span>
                                            {%- endif -%}
                                            {% if document.metadata.date.iso is defined and document.metadata.date.iso -%}
                                                <time datetime="{{ document.metadata.date.iso }}">{{ document.metadata.date.short }}</time>
                                            {%- endif %}
                                        </li>
                                    {% endif %}

                                    {%- if document.metadata.type is defined and document.metadata.type and document.metadata.type.text is defined and document.metadata.type.text %}
                                        <li class="ons-document-list__item-attribute{%- if document.metadata.file is defined and document.metadata.file %} ons-u-mr-no{% endif %}">
                                            {%- if document.metadata.type.url is defined and document.metadata.type.url %}
                                                <a class="ons-document-list__attribute-link" href="{{ document.metadata.type.url }}">
                                            {% endif %}
                                                    <span {% if not document.metadata.file and not document.metadata.type.url %}class="ons-u-fw-b"{% endif %}>{{ document.metadata.type.text }}{%- if document.metadata.type.ref is defined and document.metadata.type.ref %}: {% elif document.metadata.file is defined and document.metadata.file %},{% endif %}</span>
                                            {%- if document.metadata.type.url is defined and document.metadata.type.url %}
                                                </a>
                                            {% endif %}
                                            {%- if document.metadata.type.ref is defined and document.metadata.type.ref %}
                                                <span>{{ document.metadata.type.ref }}</span>
                                            {% endif %}
                                        </li>
                                    {% endif %}

                                    {%- if document.metadata.file is defined and document.metadata.file and document.metadata.file.fileType is defined and document.metadata.file.fileType %}

                                        <li class="ons-document-list__item-attribute" aria-hidden="true">
                                            {% set fileMetadataItems = [] %}

                                            {% if document.metadata.file.fileType is defined and document.metadata.file.fileType %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileType), fileMetadataItems) %}{% endif %}
                                            {% if document.metadata.file.fileSize is defined and document.metadata.file.fileSize %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileSize), fileMetadataItems) %}{% endif %}
                                            {% if document.metadata.file.filePages is defined and document.metadata.file.filePages %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.filePages), fileMetadataItems) %}{% endif %}

                                            {{ fileMetadataItems | join(', ') }}
                                        </li>

                                    {% endif -%}
                                </ul>

                            {% endif %}
                        </div>

                        {% if document.description is defined and document.description %}
                            <div class="ons-document-list__item-description">{{ document.description | safe }}</div>
                        {% endif %}

                    </div>

            {% if document.fullWidth is defined and document.fullWidth == true %}

                </div>

            {% endif %}

        </li>
        {% endfor %}
    </ul>

{% endmacro %}
.ons-document-list {
  @extend .ons-list--bare;

  margin-bottom: 0;

  &__item {
    border-bottom: 1px solid $color-borders-list;
    margin: 0 0 1.5rem;
    padding: 0 0 1.5rem;

    @include mq(xs) {
      align-items: flex-start;
      display: flex;
    }

    &:last-of-type {
      border-bottom: 0;
      margin: 0;
    }
  }

  &__item-image {
    flex: 0 0 auto;
    margin-bottom: 1rem;
    width: 136px;

    @include mq(xs) {
      margin-right: 1.5rem;
    }

    @include mq(m) {
      margin-bottom: 0;
    }
  }

  &__item-image & {
    &__image-link {
      &--placeholder {
        height: 96px;
      }
    }
  }

  &__item-image--file {
    width: 96px;
  }

  &__item-image--file & {
    &__image-link {
      border-color: $color-borders-document-image;

      &--placeholder {
        height: 136px;
      }
    }
  }

  &__image-link {
    border: 2px solid transparent;
    box-sizing: content-box;
    display: block;
    width: 100%;

    &:focus {
      background-color: $color-placeholder !important;
      border: 2px solid $color-borders-document-image-focus;
      box-shadow: none;
      outline: 4px solid $color-focus !important;
      outline-offset: 0;
    }

    &--placeholder {
      background-clip: padding-box;
      background-color: $color-borders-document-image;
      background-image: url("data:image/svg+xml;charset=UTF-8,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3e%3cpath fill='%23fff' d='M0 19.39c.49-1 1-2 1.55-2.93A31.59 31.59 0 0 1 0 11.72v7.67ZM3 0S0 0 0 3.7v2a34.85 34.85 0 0 0 2.17 9.76A31.2 31.2 0 0 1 8.3 8.3c4.84-4.16 11.36-7 20.21-8.29Zm28.84 2c-10.11 1-17 3.86-22 8.1a29.78 29.78 0 0 0-6.49 8C7.26 25.65 14.66 31.19 27 32h1.21A3.71 3.71 0 0 0 32 27.91V2a.41.41 0 0 1-.16 0Zm-26 21.49a25.94 25.94 0 0 1-3-4.4A48 48 0 0 0 0 25.71V32h20.23a26.41 26.41 0 0 1-14.39-8.49Z'/%3e%3c/svg%3e");
      background-position: center;
      background-repeat: no-repeat;
      background-size: 32px 32px;
      height: 100%;
    }
  }

  &__item-metadata {
    @extend .ons-list--bare;

    line-height: 1.2 !important;
  }

  &__item-attribute {
    color: $color-text-metadata;
    display: inline-block;
    margin: 0 1rem 0 0;

    @extend .ons-u-fs-s;
  }

  &__attribute-link {
    color: inherit;

    &:hover {
      color: $color-text-metadata;
      text-decoration: underline solid $color-text-metadata 2px;
    }
  }

  &__item-description {
    margin-bottom: 0;
    max-width: 660px; // Equivalent to 8 Columns

    p:last-of-type {
      margin-bottom: 0;
    }
  }
}

// Featured document
.ons-document-list {
  &__item {
    &--featured {
      background-color: $color-banner-bg;
      border-bottom: none;
      display: block;
      padding: 2rem;

      @include mq(m) {
        align-items: flex-start;
        display: flex;

        .ons-container {
          display: flex;
        }
      }

      // Increase thumbnail image size
      .ons-document-list__item-image {
        width: 248px;

        & &__image-link {
          &--placeholder {
            height: 96px;
          }
        }

        @include mq(m) {
          margin-right: 2.5rem;
          width: 379px;

          & &__image-link {
            &--placeholder {
              height: 248px;
            }
          }
        }
      }

      // Show metadata above title
      .ons-document-list__item-header {
        &--reverse {
          display: flex;
          flex-direction: column-reverse;
          margin-bottom: 0.5rem;
        }
      }

      // Increase font size
      .ons-document-list__item-title {
        @extend .ons-u-fs-l;
      }

      // If featured item is first in same list
      & + .ons-document-list__item {
        border-top: none;
        margin-top: 0;
      }
    }

    // If featured item is full width
    &--full-width {
      padding: 2rem 0;
    }
  }
}

News articles

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

<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/cons-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>
{% 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/cons-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.'
        }
    ]
}) }}
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
titleTag string false The HTML heading tag to wrap each document list item’s title to make sure the headings have the correct semantic order on the page. Defaults to h2

Document

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 string true The title for the document
url string true The URL for the document link (either a file or web page)
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
wide boolean false Set to true to increase the maximum width of the layout container to 1280px.

Thumbnail

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

Metadata

Name Type Required Description
type <Object>Type 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

Type

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”.

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”
{% macro onsDocumentList(params) %}
    <ul{% if params.id is defined and params.id %} id="{{ params.id }}"{% endif %} class="ons-document-list{{ ' ' + params.classes if params.classes is defined and params.classes else '' }}"{% if params.attributes is defined and params.attributes %}{% for attribute, value in (params.attributes.items() if params.attributes is mapping and params.attributes.items else params.attributes) %} {{attribute}}="{{value}}"{% endfor %}{% endif %}>
        {% for document in (params.documents if params.documents is iterable else params.documents.items()) %}

        <li class="ons-document-list__item{{ ' ons-document-list__item--featured' if document.featured is defined and document.featured }}{{ ' ons-document-list__item--full-width' if document.fullWidth is defined and document.fullWidth == true }}{{ ' ' + document.classes if document.classes is defined and document.classes else '' }}"{% if document.attributes is defined and document.attributes %}{% for attribute, value in (document.attributes.items() if document.attributes is mapping and document.attributes.items else document.attributes) %} {{attribute}}="{{value}}"{% endfor %}{% endif %}>

            {% if document.fullWidth is defined and document.fullWidth == true %}

                <div class="ons-container{{ ' ons-container--wide' if document.wide is defined and document.wide == true }}">

            {% endif %}

                    {% if document.thumbnail is defined or document.thumbnail == true %}

                        <div class="ons-document-list__item-image{%- if document.metadata.file is defined and document.metadata.file %} ons-document-list__item-image--file{% endif %}" aria-hidden="true">
                            <a class="ons-document-list__image-link{{ ' ons-document-list__image-link--placeholder' if not document.thumbnail.smallSrc }}" href="{{ document.url }}" tabindex="-1">
                                {% if document.thumbnail.smallSrc is defined and document.thumbnail.smallSrc and document.thumbnail.largeSrc is defined and document.thumbnail.largeSrc %}
                                    <img srcset="{{ document.thumbnail.smallSrc }} 1x, {{ document.thumbnail.largeSrc }} 2x" src="{{ document.thumbnail.smallSrc }}" alt="" loading="lazy">
                                {% endif %}
                            </a>
                        </div>

                    {% endif %}

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

                        <div class="ons-document-list__item-header{{ ' ons-document-list__item-header--reverse' if document.showMetadataFirst is defined and document.showMetadataFirst == true }}">

                            {% set titleTag = params.titleTag | default("h2") %}

                            <{{ titleTag }} class="ons-document-list__item-title ons-u-fs-m ons-u-mt-no ons-u-mb-xs">
                                <a href="{{ document.url }}">{{ document.title }}
                                {%- if document.metadata is defined and document.metadata and document.metadata.file is defined and document.metadata.file %}
                                <span class="ons-u-vh">
                                    {% set fileMetadataItems = [] %}
                                    {% if document.metadata.file.fileType is defined and document.metadata.file.fileType %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileType + ' document download'), fileMetadataItems) %}{% endif %}
                                    {% if document.metadata.file.fileSize is defined and document.metadata.file.fileSize %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileSize), fileMetadataItems) %}{% endif %}
                                    {% if document.metadata.file.filePages is defined and document.metadata.file.filePages %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.filePages), fileMetadataItems) %}{% endif %}

                                    , {{ fileMetadataItems | join(', ') }}

                                {% endif %}

                                </span></a>
                            </{{ titleTag }}>

                            {%- if document.metadata is defined and document.metadata %}

                                <ul class="ons-document-list__item-metadata{% if document.description is defined and document.description %} ons-u-mb-xs{% else %} ons-u-mb-no{% endif %}">

                                    {%- if document.metadata.date is defined and document.metadata.date %}
                                        <li class="ons-document-list__item-attribute">
                                            {% if document.metadata.date -%}
                                                {% set prefixClasses = "ons-u-fw-b" if document.metadata.date.showPrefix is defined and document.metadata.date.showPrefix == true else "ons-u-vh" %}
                                                <span class="{{ prefixClasses }}">{{ document.metadata.date.prefix | default("Published") }}: </span>
                                            {%- endif -%}
                                            {% if document.metadata.date.iso is defined and document.metadata.date.iso -%}
                                                <time datetime="{{ document.metadata.date.iso }}">{{ document.metadata.date.short }}</time>
                                            {%- endif %}
                                        </li>
                                    {% endif %}

                                    {%- if document.metadata.type is defined and document.metadata.type and document.metadata.type.text is defined and document.metadata.type.text %}
                                        <li class="ons-document-list__item-attribute{%- if document.metadata.file is defined and document.metadata.file %} ons-u-mr-no{% endif %}">
                                            {%- if document.metadata.type.url is defined and document.metadata.type.url %}
                                                <a class="ons-document-list__attribute-link" href="{{ document.metadata.type.url }}">
                                            {% endif %}
                                                    <span {% if not document.metadata.file and not document.metadata.type.url %}class="ons-u-fw-b"{% endif %}>{{ document.metadata.type.text }}{%- if document.metadata.type.ref is defined and document.metadata.type.ref %}: {% elif document.metadata.file is defined and document.metadata.file %},{% endif %}</span>
                                            {%- if document.metadata.type.url is defined and document.metadata.type.url %}
                                                </a>
                                            {% endif %}
                                            {%- if document.metadata.type.ref is defined and document.metadata.type.ref %}
                                                <span>{{ document.metadata.type.ref }}</span>
                                            {% endif %}
                                        </li>
                                    {% endif %}

                                    {%- if document.metadata.file is defined and document.metadata.file and document.metadata.file.fileType is defined and document.metadata.file.fileType %}

                                        <li class="ons-document-list__item-attribute" aria-hidden="true">
                                            {% set fileMetadataItems = [] %}

                                            {% if document.metadata.file.fileType is defined and document.metadata.file.fileType %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileType), fileMetadataItems) %}{% endif %}
                                            {% if document.metadata.file.fileSize is defined and document.metadata.file.fileSize %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileSize), fileMetadataItems) %}{% endif %}
                                            {% if document.metadata.file.filePages is defined and document.metadata.file.filePages %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.filePages), fileMetadataItems) %}{% endif %}

                                            {{ fileMetadataItems | join(', ') }}
                                        </li>

                                    {% endif -%}
                                </ul>

                            {% endif %}
                        </div>

                        {% if document.description is defined and document.description %}
                            <div class="ons-document-list__item-description">{{ document.description | safe }}</div>
                        {% endif %}

                    </div>

            {% if document.fullWidth is defined and document.fullWidth == true %}

                </div>

            {% endif %}

        </li>
        {% endfor %}
    </ul>

{% endmacro %}
.ons-document-list {
  @extend .ons-list--bare;

  margin-bottom: 0;

  &__item {
    border-bottom: 1px solid $color-borders-list;
    margin: 0 0 1.5rem;
    padding: 0 0 1.5rem;

    @include mq(xs) {
      align-items: flex-start;
      display: flex;
    }

    &:last-of-type {
      border-bottom: 0;
      margin: 0;
    }
  }

  &__item-image {
    flex: 0 0 auto;
    margin-bottom: 1rem;
    width: 136px;

    @include mq(xs) {
      margin-right: 1.5rem;
    }

    @include mq(m) {
      margin-bottom: 0;
    }
  }

  &__item-image & {
    &__image-link {
      &--placeholder {
        height: 96px;
      }
    }
  }

  &__item-image--file {
    width: 96px;
  }

  &__item-image--file & {
    &__image-link {
      border-color: $color-borders-document-image;

      &--placeholder {
        height: 136px;
      }
    }
  }

  &__image-link {
    border: 2px solid transparent;
    box-sizing: content-box;
    display: block;
    width: 100%;

    &:focus {
      background-color: $color-placeholder !important;
      border: 2px solid $color-borders-document-image-focus;
      box-shadow: none;
      outline: 4px solid $color-focus !important;
      outline-offset: 0;
    }

    &--placeholder {
      background-clip: padding-box;
      background-color: $color-borders-document-image;
      background-image: url("data:image/svg+xml;charset=UTF-8,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3e%3cpath fill='%23fff' d='M0 19.39c.49-1 1-2 1.55-2.93A31.59 31.59 0 0 1 0 11.72v7.67ZM3 0S0 0 0 3.7v2a34.85 34.85 0 0 0 2.17 9.76A31.2 31.2 0 0 1 8.3 8.3c4.84-4.16 11.36-7 20.21-8.29Zm28.84 2c-10.11 1-17 3.86-22 8.1a29.78 29.78 0 0 0-6.49 8C7.26 25.65 14.66 31.19 27 32h1.21A3.71 3.71 0 0 0 32 27.91V2a.41.41 0 0 1-.16 0Zm-26 21.49a25.94 25.94 0 0 1-3-4.4A48 48 0 0 0 0 25.71V32h20.23a26.41 26.41 0 0 1-14.39-8.49Z'/%3e%3c/svg%3e");
      background-position: center;
      background-repeat: no-repeat;
      background-size: 32px 32px;
      height: 100%;
    }
  }

  &__item-metadata {
    @extend .ons-list--bare;

    line-height: 1.2 !important;
  }

  &__item-attribute {
    color: $color-text-metadata;
    display: inline-block;
    margin: 0 1rem 0 0;

    @extend .ons-u-fs-s;
  }

  &__attribute-link {
    color: inherit;

    &:hover {
      color: $color-text-metadata;
      text-decoration: underline solid $color-text-metadata 2px;
    }
  }

  &__item-description {
    margin-bottom: 0;
    max-width: 660px; // Equivalent to 8 Columns

    p:last-of-type {
      margin-bottom: 0;
    }
  }
}

// Featured document
.ons-document-list {
  &__item {
    &--featured {
      background-color: $color-banner-bg;
      border-bottom: none;
      display: block;
      padding: 2rem;

      @include mq(m) {
        align-items: flex-start;
        display: flex;

        .ons-container {
          display: flex;
        }
      }

      // Increase thumbnail image size
      .ons-document-list__item-image {
        width: 248px;

        & &__image-link {
          &--placeholder {
            height: 96px;
          }
        }

        @include mq(m) {
          margin-right: 2.5rem;
          width: 379px;

          & &__image-link {
            &--placeholder {
              height: 248px;
            }
          }
        }
      }

      // Show metadata above title
      .ons-document-list__item-header {
        &--reverse {
          display: flex;
          flex-direction: column-reverse;
          margin-bottom: 0.5rem;
        }
      }

      // Increase font size
      .ons-document-list__item-title {
        @extend .ons-u-fs-l;
      }

      // If featured item is first in same list
      & + .ons-document-list__item {
        border-top: none;
        margin-top: 0;
      }
    }

    // If featured item is full width
    &--full-width {
      padding: 2rem 0;
    }
  }
}

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.

<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>

{% 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.'
        }
    ]
}) }}
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
titleTag string false The HTML heading tag to wrap each document list item’s title to make sure the headings have the correct semantic order on the page. Defaults to h2

Document

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 string true The title for the document
url string true The URL for the document link (either a file or web page)
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
wide boolean false Set to true to increase the maximum width of the layout container to 1280px.

Thumbnail

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

Metadata

Name Type Required Description
type <Object>Type 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

Type

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”.

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”
{% macro onsDocumentList(params) %}
    <ul{% if params.id is defined and params.id %} id="{{ params.id }}"{% endif %} class="ons-document-list{{ ' ' + params.classes if params.classes is defined and params.classes else '' }}"{% if params.attributes is defined and params.attributes %}{% for attribute, value in (params.attributes.items() if params.attributes is mapping and params.attributes.items else params.attributes) %} {{attribute}}="{{value}}"{% endfor %}{% endif %}>
        {% for document in (params.documents if params.documents is iterable else params.documents.items()) %}

        <li class="ons-document-list__item{{ ' ons-document-list__item--featured' if document.featured is defined and document.featured }}{{ ' ons-document-list__item--full-width' if document.fullWidth is defined and document.fullWidth == true }}{{ ' ' + document.classes if document.classes is defined and document.classes else '' }}"{% if document.attributes is defined and document.attributes %}{% for attribute, value in (document.attributes.items() if document.attributes is mapping and document.attributes.items else document.attributes) %} {{attribute}}="{{value}}"{% endfor %}{% endif %}>

            {% if document.fullWidth is defined and document.fullWidth == true %}

                <div class="ons-container{{ ' ons-container--wide' if document.wide is defined and document.wide == true }}">

            {% endif %}

                    {% if document.thumbnail is defined or document.thumbnail == true %}

                        <div class="ons-document-list__item-image{%- if document.metadata.file is defined and document.metadata.file %} ons-document-list__item-image--file{% endif %}" aria-hidden="true">
                            <a class="ons-document-list__image-link{{ ' ons-document-list__image-link--placeholder' if not document.thumbnail.smallSrc }}" href="{{ document.url }}" tabindex="-1">
                                {% if document.thumbnail.smallSrc is defined and document.thumbnail.smallSrc and document.thumbnail.largeSrc is defined and document.thumbnail.largeSrc %}
                                    <img srcset="{{ document.thumbnail.smallSrc }} 1x, {{ document.thumbnail.largeSrc }} 2x" src="{{ document.thumbnail.smallSrc }}" alt="" loading="lazy">
                                {% endif %}
                            </a>
                        </div>

                    {% endif %}

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

                        <div class="ons-document-list__item-header{{ ' ons-document-list__item-header--reverse' if document.showMetadataFirst is defined and document.showMetadataFirst == true }}">

                            {% set titleTag = params.titleTag | default("h2") %}

                            <{{ titleTag }} class="ons-document-list__item-title ons-u-fs-m ons-u-mt-no ons-u-mb-xs">
                                <a href="{{ document.url }}">{{ document.title }}
                                {%- if document.metadata is defined and document.metadata and document.metadata.file is defined and document.metadata.file %}
                                <span class="ons-u-vh">
                                    {% set fileMetadataItems = [] %}
                                    {% if document.metadata.file.fileType is defined and document.metadata.file.fileType %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileType + ' document download'), fileMetadataItems) %}{% endif %}
                                    {% if document.metadata.file.fileSize is defined and document.metadata.file.fileSize %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileSize), fileMetadataItems) %}{% endif %}
                                    {% if document.metadata.file.filePages is defined and document.metadata.file.filePages %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.filePages), fileMetadataItems) %}{% endif %}

                                    , {{ fileMetadataItems | join(', ') }}

                                {% endif %}

                                </span></a>
                            </{{ titleTag }}>

                            {%- if document.metadata is defined and document.metadata %}

                                <ul class="ons-document-list__item-metadata{% if document.description is defined and document.description %} ons-u-mb-xs{% else %} ons-u-mb-no{% endif %}">

                                    {%- if document.metadata.date is defined and document.metadata.date %}
                                        <li class="ons-document-list__item-attribute">
                                            {% if document.metadata.date -%}
                                                {% set prefixClasses = "ons-u-fw-b" if document.metadata.date.showPrefix is defined and document.metadata.date.showPrefix == true else "ons-u-vh" %}
                                                <span class="{{ prefixClasses }}">{{ document.metadata.date.prefix | default("Published") }}: </span>
                                            {%- endif -%}
                                            {% if document.metadata.date.iso is defined and document.metadata.date.iso -%}
                                                <time datetime="{{ document.metadata.date.iso }}">{{ document.metadata.date.short }}</time>
                                            {%- endif %}
                                        </li>
                                    {% endif %}

                                    {%- if document.metadata.type is defined and document.metadata.type and document.metadata.type.text is defined and document.metadata.type.text %}
                                        <li class="ons-document-list__item-attribute{%- if document.metadata.file is defined and document.metadata.file %} ons-u-mr-no{% endif %}">
                                            {%- if document.metadata.type.url is defined and document.metadata.type.url %}
                                                <a class="ons-document-list__attribute-link" href="{{ document.metadata.type.url }}">
                                            {% endif %}
                                                    <span {% if not document.metadata.file and not document.metadata.type.url %}class="ons-u-fw-b"{% endif %}>{{ document.metadata.type.text }}{%- if document.metadata.type.ref is defined and document.metadata.type.ref %}: {% elif document.metadata.file is defined and document.metadata.file %},{% endif %}</span>
                                            {%- if document.metadata.type.url is defined and document.metadata.type.url %}
                                                </a>
                                            {% endif %}
                                            {%- if document.metadata.type.ref is defined and document.metadata.type.ref %}
                                                <span>{{ document.metadata.type.ref }}</span>
                                            {% endif %}
                                        </li>
                                    {% endif %}

                                    {%- if document.metadata.file is defined and document.metadata.file and document.metadata.file.fileType is defined and document.metadata.file.fileType %}

                                        <li class="ons-document-list__item-attribute" aria-hidden="true">
                                            {% set fileMetadataItems = [] %}

                                            {% if document.metadata.file.fileType is defined and document.metadata.file.fileType %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileType), fileMetadataItems) %}{% endif %}
                                            {% if document.metadata.file.fileSize is defined and document.metadata.file.fileSize %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileSize), fileMetadataItems) %}{% endif %}
                                            {% if document.metadata.file.filePages is defined and document.metadata.file.filePages %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.filePages), fileMetadataItems) %}{% endif %}

                                            {{ fileMetadataItems | join(', ') }}
                                        </li>

                                    {% endif -%}
                                </ul>

                            {% endif %}
                        </div>

                        {% if document.description is defined and document.description %}
                            <div class="ons-document-list__item-description">{{ document.description | safe }}</div>
                        {% endif %}

                    </div>

            {% if document.fullWidth is defined and document.fullWidth == true %}

                </div>

            {% endif %}

        </li>
        {% endfor %}
    </ul>

{% endmacro %}
.ons-document-list {
  @extend .ons-list--bare;

  margin-bottom: 0;

  &__item {
    border-bottom: 1px solid $color-borders-list;
    margin: 0 0 1.5rem;
    padding: 0 0 1.5rem;

    @include mq(xs) {
      align-items: flex-start;
      display: flex;
    }

    &:last-of-type {
      border-bottom: 0;
      margin: 0;
    }
  }

  &__item-image {
    flex: 0 0 auto;
    margin-bottom: 1rem;
    width: 136px;

    @include mq(xs) {
      margin-right: 1.5rem;
    }

    @include mq(m) {
      margin-bottom: 0;
    }
  }

  &__item-image & {
    &__image-link {
      &--placeholder {
        height: 96px;
      }
    }
  }

  &__item-image--file {
    width: 96px;
  }

  &__item-image--file & {
    &__image-link {
      border-color: $color-borders-document-image;

      &--placeholder {
        height: 136px;
      }
    }
  }

  &__image-link {
    border: 2px solid transparent;
    box-sizing: content-box;
    display: block;
    width: 100%;

    &:focus {
      background-color: $color-placeholder !important;
      border: 2px solid $color-borders-document-image-focus;
      box-shadow: none;
      outline: 4px solid $color-focus !important;
      outline-offset: 0;
    }

    &--placeholder {
      background-clip: padding-box;
      background-color: $color-borders-document-image;
      background-image: url("data:image/svg+xml;charset=UTF-8,%3csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3e%3cpath fill='%23fff' d='M0 19.39c.49-1 1-2 1.55-2.93A31.59 31.59 0 0 1 0 11.72v7.67ZM3 0S0 0 0 3.7v2a34.85 34.85 0 0 0 2.17 9.76A31.2 31.2 0 0 1 8.3 8.3c4.84-4.16 11.36-7 20.21-8.29Zm28.84 2c-10.11 1-17 3.86-22 8.1a29.78 29.78 0 0 0-6.49 8C7.26 25.65 14.66 31.19 27 32h1.21A3.71 3.71 0 0 0 32 27.91V2a.41.41 0 0 1-.16 0Zm-26 21.49a25.94 25.94 0 0 1-3-4.4A48 48 0 0 0 0 25.71V32h20.23a26.41 26.41 0 0 1-14.39-8.49Z'/%3e%3c/svg%3e");
      background-position: center;
      background-repeat: no-repeat;
      background-size: 32px 32px;
      height: 100%;
    }
  }

  &__item-metadata {
    @extend .ons-list--bare;

    line-height: 1.2 !important;
  }

  &__item-attribute {
    color: $color-text-metadata;
    display: inline-block;
    margin: 0 1rem 0 0;

    @extend .ons-u-fs-s;
  }

  &__attribute-link {
    color: inherit;

    &:hover {
      color: $color-text-metadata;
      text-decoration: underline solid $color-text-metadata 2px;
    }
  }

  &__item-description {
    margin-bottom: 0;
    max-width: 660px; // Equivalent to 8 Columns

    p:last-of-type {
      margin-bottom: 0;
    }
  }
}

// Featured document
.ons-document-list {
  &__item {
    &--featured {
      background-color: $color-banner-bg;
      border-bottom: none;
      display: block;
      padding: 2rem;

      @include mq(m) {
        align-items: flex-start;
        display: flex;

        .ons-container {
          display: flex;
        }
      }

      // Increase thumbnail image size
      .ons-document-list__item-image {
        width: 248px;

        & &__image-link {
          &--placeholder {
            height: 96px;
          }
        }

        @include mq(m) {
          margin-right: 2.5rem;
          width: 379px;

          & &__image-link {
            &--placeholder {
              height: 248px;
            }
          }
        }
      }

      // Show metadata above title
      .ons-document-list__item-header {
        &--reverse {
          display: flex;
          flex-direction: column-reverse;
          margin-bottom: 0.5rem;
        }
      }

      // Increase font size
      .ons-document-list__item-title {
        @extend .ons-u-fs-l;
      }

      // If featured item is first in same list
      & + .ons-document-list__item {
        border-top: none;
        margin-top: 0;
      }
    }

    // If featured item is full width
    &--full-width {
      padding: 2rem 0;
    }
  }
}

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 component

Let us know how we could improve this component or share your user research findings. Discuss the ‘Document list’ component on GitHub