Favorites

A Guide to the HTML download Attribute

☕
Enjoying this site?

Help keep it running with a small coffee donation. Every bit of support is appreciated!

Buy us a coffee
Download Attribute

What does the download attribute do?

When you link to a file such as a PDF or an image, browsers usually open it rather than save it. Adding the download attribute to the link asks the browser to save the file to the visitor's device instead:

<a href="/files/brochure.pdf" download>Download our brochure (PDF, 1.2 MB)</a>

It's a single attribute on an ordinary <a> element, with no JavaScript required, and it works for any type of file: documents, images, spreadsheets, audio, video and ZIP archives.

Syntax and custom file names

Used on its own, download keeps the file's original name. Give it a value, and the browser suggests that name instead:

<!-- Saved as report_2024_final_v3.pdf -->
<a href="/reports/report_2024_final_v3.pdf" download>Annual report</a>

<!-- Saved as CSSPortal-annual-report-2024.pdf -->
<a href="/reports/report_2024_final_v3.pdf" download="CSSPortal-annual-report-2024.pdf">Annual report</a>

Custom names are handy when files on your server have technical or auto-generated names that wouldn't mean much in someone's Downloads folder.

  • Include the file extension, such as .pdf or .csv, so the visitor's device knows which app opens it. Some browsers adjust or add the extension to match the file's real type.
  • Keep names simple. Browsers remove or replace characters that aren't allowed in file names, such as / and \, so a name can't put the file into a different folder.
  • The visitor has the final say. Depending on their settings, the browser may ask where to save the file, and they can rename it.

Try it: download files made by the page

The download attribute also works with files your page creates itself, which is perfect for exporting data, saving notes or generating images in the browser.

A data: URL

A data: URL contains the file's contents directly inside the link. This one downloads a small text file:

<a href="data:text/plain;charset=utf-8,Hello%20from%20CSSPortal!" download="hello.txt">Download hello.txt</a>

Data URLs are fine for tiny files, but the content has to be encoded into the link itself, so they quickly become unwieldy.

A Blob made with JavaScript

For anything bigger, or for content that changes, JavaScript can create a file in memory, called a Blob, and give it a temporary address with URL.createObjectURL(). Type some notes below and download them, or export the sample data as a spreadsheet-friendly CSV file:

Results
function downloadFile(contents, fileName, type) {
  const blob = new Blob([contents], { type });
  const url = URL.createObjectURL(blob);    // a temporary blob: address

  const link = document.createElement('a');
  link.href = url;
  link.download = fileName;
  link.click();                             // start the download

  setTimeout(() => URL.revokeObjectURL(url), 1000);  // free the memory
}

// Download the notes as a text file
downloadFile(notes.value, 'my-notes.txt', 'text/plain');

// Download data as a CSV file
const csv = 'Name,Score\nAda,92\nGrace,88\nAlan,95';
downloadFile(csv, 'scores.csv', 'text/csv');
  • new Blob() creates a file in memory from your content, with a MIME type (a label for the kind of file, such as text/csv).
  • URL.createObjectURL() gives the Blob a temporary blob: address that a link can point to.
  • URL.revokeObjectURL() frees the memory once the download has started.

Tip: if a CSV file with accented letters looks garbled when opened in Excel, add an invisible marker called a byte order mark to the start of the text: '' + csv. It tells Excel the file uses UTF-8.

The same-origin rule

For security, browsers only honour the download attribute for files from the same origin as the page (the same protocol, domain and port), or for blob: and data: URLs like the ones above. For a file on a different domain, the attribute is ignored, and the browser does whatever it normally would, which for a PDF usually means opening it.

<!-- On www.example.com: works -->
<a href="/files/guide.pdf" download>Download the guide</a>

<!-- On www.example.com: download is ignored, as the file is on another domain -->
<a href="https://cdn.another-site.com/guide.pdf" download>Download the guide</a>

Note that a different subdomain counts as a different origin too, so a file on files.example.com is cross-origin for a page on www.example.com.

The Content-Disposition header

The most reliable way to make a file download is on the server, with the Content-Disposition HTTP header. It works for any link, from any page, on any domain:

Content-Disposition: attachment; filename="annual-report-2024.pdf"
  • attachment tells the browser to save the file instead of displaying it.
  • filename suggests a name for the saved file.

How you set the header depends on your server or hosting. On an Apache server, for example, you can add it for all PDFs in a folder with an .htaccess file:

<FilesMatch "\.pdf$">
  Header set Content-Disposition "attachment"
</FilesMatch>

Good to know: if a file is sent with a Content-Disposition header that includes a file name, that name takes priority over the one in the download attribute.

A link that downloads a file behaves differently from one that opens a page, so it's kind to let people know before they click:

  • Say what they're getting: include the file type and size in the link text, as in "Annual report (PDF, 2.4 MB)". People on slow or limited connections can decide whether to download, and screen readers (software that reads pages aloud) announce the information too.
  • Use a download icon alongside the text if you like, but hide it from screen readers with aria-hidden="true", as the text already explains it.
  • Avoid vague link text like "Click here". Link text should make sense on its own.
  • Choose helpful file names that will make sense later in someone's Downloads folder, such as CSSPortal-annual-report-2024.pdf.
  • Offer common formats, such as PDF for documents and CSV for data, which open on most devices.
<a href="/reports/annual-report-2024.pdf" download>
  <svg aria-hidden="true" …>…</svg>
  Annual report 2024 (PDF, 2.4 MB)
</a>

Browser support and gotchas

The download attribute works in every current major browser, including Safari on iPhone and iPad, and has done for many years. Browsers that ignore it simply follow the link as normal, so it's a safe enhancement to add.

Out of date: the original version of this post spent a long section on Internet Explorer, which doesn't support the attribute. Microsoft retired Internet Explorer in 2022, so there's no need to plan for it any more.

  • Cross-origin files ignore it, as covered above.
  • Sandboxed iframes block downloads unless the iframe's sandbox attribute includes allow-downloads.
  • It only works on links: <a> elements, plus <area> in image maps. It has no effect on buttons or forms.
  • Don't use it for web pages. Linking to an HTML page with download saves the page as a file instead of opening it, which is rarely what people expect.
  • The server's header wins. A Content-Disposition file name overrides the attribute's value.

Wrapping up

The download attribute turns any same-origin link into a download, with an optional friendlier file name. It also works with blob: and data: URLs, so your pages can create files on the fly. For files on other domains, use the Content-Disposition header on the server, and always tell people what they're about to download, including the file type and size.

☕
Enjoying this site?

Help keep it running with a small coffee donation. Every bit of support is appreciated!

Buy us a coffee