File Download Links

Owned by David Fourney (Unlicensed)
Last updated: Sept 22, 2019
2 min read

All users should be informed when a link will open a document or download a file, such as a PDF file, rather than open an HTML page. For this reason file download links must indicate:

  • The format of the file (e.g., PDF, Word, etc.).
  • Whether the link also opens in a new window and/or is external to the site.

In addition to the file type of the download, other information (e.g., the size of the download) should be included where useful.

Provide information about the file format of the link target so all users understand what kind of file will be opened.

  • e.g., Add "(PDF)" in the link text of PDF document links.
Adding "(PDF)" to the link text of a PDF document link
<a href="https://www.toronto.ca/example.pdf">Example Document (PDF)</a>
  • e.g., Add a PDF icon next to PDF document links. Make the icon part of the link text by making the alt attribute programmatically part of the link.
Adding a PDF icon next to a PDF document link
<a href="https://www.toronto.ca/example.pdf">Example Document <img src="https://www.toronto.ca/wp-content/themes/cot/img/icon-link-external.svg" alt="PDF format"></a>

Alternatively, use the aria-describedby property to programmatically connect the PDF icon with the link. Note: This approach requires a different id for each PDF icon.

Using aria-describedby to programmatically connect a PDF icon with a linked document
<a href="https://www.toronto.ca/example.pdf" aria-describedby='pdf1'>Example Document</a><span id='pdf1'> <img alt="PDF format" src="https://www.toronto.ca/wp-content/themes/cot/img/icon-link-external.svg"></span>

If the download link also opens in a new window (i.e., the link includes a target attribute), the document type icon should include some visual indication of this and screen reader users must be informed.

  • e.g.: A PDF file that opens in a new window. Add "(PDF)" in the link text, an "external link" icon as an inline image, and appropriate alt text for the icon.
Adding "(PDF)" to the link text and an "external link" icon
<a href="https://www.toronto.ca/example.pdf" target="_blank">Example Document (PDF)
    <img alt="Opens in new window" class="cot-external-link cot-open-new-window" src="https://www.toronto.ca/wp-content/themes/cot/img/icon-link-external.svg"></a>
  • e.g.: Add an "PDF external link" icon as a CSS background image, with appropriate screen reader-only text (note the additional space in the <span>).
Using CSS to add an accessible "PDF external link" icon
<!-- HTML -->
<a href="https://www.toronto.ca/example.pdf" target="_blank">Example Documents (PDF)
    <span class="sr-only"> PDF file opens in new window</span>
</a>


<!-- CSS -->
a[target="_blank"] {
...
}

For more information on how to communicate that a link opens a new window or an external site, see the Links that open in new window page.

  • Adding an icon via CSS renders it essentially invisible to screen reader users. Since screen readers do not read CSS images, never embed critical information in CSS.
  • Always include the file format description (e.g., “PDF”) after the link text, not before. This ensures screen reader users know the target and purpose of the link first.
  • Generally, HTML’s download attribute should be avoided. This attribute tells the browser to download the linked file rather than opening it in the browser. Using it takes away the user’s ability to choose whether to view it in the browser.

W3C: H80: Identifying the purpose of a link using link text combined with the preceding heading element