File download

A block containing information about a file with a link to download it

Sample HTML

<div class="ds_file-download">
    <div class="ds_file-download__thumbnail">
        <a data-button="document-cover" class="ds_file-download__thumbnail-link" aria-hidden="true" tabindex="-1" href="#">
            <span class="visually-hidden">Document cover image</span>
            <img class="ds_file-download__thumbnail-image" src="/assets/images/graphics/ai-publication-cover.png" alt="" />
        </a>
    </div>

    <div class="ds_file-download__content">
        <p class="ds_file-download__title" id="file-title-1">Scotland's Artificial Intelligence Strategy - Trustworthy, Ethical and Inclusive</p>

        <div id="file-download-1" class="ds_file-download__details">
            <dl class="ds_metadata  ds_metadata--inline">
                <div class="ds_metadata__item">
                    <dt class="ds_metadata__key  visually-hidden">File type</dt>
                    <dd class="ds_metadata__value">44 page PDF<span class="visually-hidden">,</span></dd>
                </div>

                <div class="ds_metadata__item">
                    <dt class="ds_metadata__key  visually-hidden">File size</dt>
                    <dd class="ds_metadata__value">7.2 MB</dd>
                </div>
            </dl>
        </div>

        <div>
            <a aria-labelledby="file-title-1" aria-describedby="file-download-1" href="#" class="ds_file-download__button  ds_button  ds_button--small  ds_button--secondary  ds_no-margin">
                Download
            </a>
        </div>
    </div>
</div>

About this component

The file download component presents a file that the user can download, with some supporting information.

The component features:

  • the title of the file
  • information about the file such as its file format and size
  • a download link
  • a thumbnail image

Both the thumbnail image and the download link can be clicked on to download the file.

Why we use this component

When you do not want to have a simple text link to a file, the file download component provides a consistent and eye-catching way of presenting files for download. It provides useful information about the file that can help users to decide whether or not to download it.

Other versions of this component

Generic thumbnail image

Sample HTML

<div class="ds_file-download">
    <div class="ds_file-download__thumbnail">
        <a class="ds_file-download__thumbnail-link" aria-hidden="true" tabindex="-1" href="#">
            <span class="visually-hidden">Document cover image</span>
            <img class="ds_file-download__thumbnail-image  ds_file-download__thumbnail-image--generic" src="/assets/images/documents/svg/pdf.svg" alt="" />
        </a>
    </div>

    <div class="ds_file-download__content">
        <p class="ds_file-download__title" id="file-title-1">Scotland's Artificial Intelligence Strategy - Trustworthy, Ethical and Inclusive</p>

        <div id="file-download-1" class="ds_file-download__details">
            <dl class="ds_metadata  ds_metadata--inline">
                <div class="ds_metadata__item">
                    <dt class="ds_metadata__key  visually-hidden">File type</dt>
                    <dd class="ds_metadata__value">44 page PDF<span class="visually-hidden">,</span></dd>
                </div>

                <div class="ds_metadata__item">
                    <dt class="ds_metadata__key  visually-hidden">File size</dt>
                    <dd class="ds_metadata__value">7.2 MB</dd>
                </div>
            </dl>
        </div>

        <div>
            <a aria-labelledby="file-title-1" aria-describedby="file-download-1" href="#" class="ds_file-download__button  ds_button  ds_button--small  ds_button--secondary  ds_no-margin">
                Download
            </a>
        </div>
    </div>
</div>

If there is no specific thumbnail image for your file, the Design System has a collection of icons for common file types that can be used instead.

Developers should note the addition of a modifier class, which is required for correct display: ds_file-download__thumbnail-image--generic
Ten icons for common file types

These icons are included in the Design System’s npm module as well as the GitHub repository and should be copied into your own project.

Highlighted file

Sample HTML

<div class="ds_file-download  ds_file-download--highlighted">
    <div class="ds_file-download__thumbnail">
        <a class="ds_file-download__thumbnail-link" aria-hidden="true" tabindex="-1" href="#">
            <span class="visually-hidden">Document cover image</span>
            <img class="ds_file-download__thumbnail-image" src="/assets/images/graphics/ai-publication-cover.png" alt="" />
        </a>
    </div>

    <div class="ds_file-download__content">
        <p class="ds_file-download__title" id="file-title-1">Scotland's Artificial Intelligence Strategy - Trustworthy, Ethical and Inclusive1</p>

        <div id="file-download-1" class="ds_file-download__details">
            <dl class="ds_metadata  ds_metadata--inline">
                <div class="ds_metadata__item">
                    <dt class="ds_metadata__key  visually-hidden">File type</dt>
                    <dd class="ds_metadata__value">44 page PDF<span class="visually-hidden">,</span></dd>
                </div>

                <div class="ds_metadata__item">
                    <dt class="ds_metadata__key  visually-hidden">File size</dt>
                    <dd class="ds_metadata__value">7.2 MB</dd>
                </div>
            </dl>
        </div>

        <div>
            <a aria-labelledby="file-title-1" aria-describedby="file-download-1" href="#" class="ds_file-download__button  ds_button  ds_button--small  ds_no-margin">
                Download
            </a>
        </div>
    </div>
</div>

A file download block can be highlighted to give it a more prominent appearance. This is useful in cases where there are many file download blocks and you want to give priority to one of them.

Highlighted blocks should be placed at the beginning of a group of file download blocks, and are most effective when used for a single file in a group.

Website analytics

To understand user behaviour, clicks on links in file download blocks can be tracked through the click URL, the click text and a data attribute showing the interaction.

To help identify clicks on the thumbnail or file icon, a span with hidden text has been added to the link.

The data attributes are added automatically by the Design System’s ‘tracking’ script.

Accessibility

While the file download component contains two links to the file, only the ‘download’ link is made available to screen readers. This avoids the repetition of having multiple links to the same item read out.

The download link uses ARIA attributes to give additional context to the link. The file’s title is used in aria-labelledby and the supporting metadata in aria-describedby.

These ARIA attributes require unique ID attributes to be set on the title and the metadata elements.

Example screen reader output

In Voiceover, the download link on the file download block shown in the examples on this page would be announced like this when it has focus: Link. Scotland’s Artificial Intelligence Strategy - Trustworthy, Ethical and Inclusive. File type: 44 page PDF, file size: 7.2 megabytes.

Feedback, help or support

If you need any help or want to give any feedback you can e-mail us at: designsystem@gov.scot

Back to top