HTML Download Attribute: Browser Support, Filename, CORS

What is the HTML download attribute?

The HTML download attribute is a boolean-or-string attribute defined by WHATWG on the anchor and area elements. When set, the browser treats the linked URL as a file to save rather than a page to open. The optional value supplies the suggested filename for the saved file.

Which browsers support the HTML download attribute?

The HTML download attribute is baseline widely available across every major desktop and mobile browser, with one notable hole: Internet Explorer never shipped support, and every browser blocks the filename hint on cross-origin URLs.

How do you use the HTML download attribute?

Add the download attribute to any anchor that points at a file the user should save. The attribute can stand alone, or it can take a string that the browser uses as the suggested filename. Same-origin, blob, and data URLs are the only paths that get the filename hint.

• Add the attribute to an anchor: Drop download into an a or area element that points at a file, for example <a href="/files/report.pdf" download>Download</a>. With no value, the browser picks a name from the URL or the Content-Disposition header.
• Set a suggested filename: Assign a string, for example download="invoice-april.pdf". Forward and back slashes are converted to underscores; the browser strips any character the filesystem rejects.
• Keep the file same-origin: Host the file on the same scheme, host, and port as the page. A cross-origin URL gets the filename dropped on Chrome and the entire attribute ignored on Firefox and Safari.
• Wire up a JavaScript download: Build the bytes in the page, wrap them in a Blob, call URL.createObjectURL, and assign the result to the href of an anchor with the download attribute. Click the anchor and revoke the URL right after.
• Verify the save dialog: Click the link in Chrome, Firefox, and Safari. The Save As prompt should show the filename you set. If it does not, check the Network tab for a Content-Disposition header that overrides the attribute.

// Same-origin download with the HTML download attribute.
// Paste into the DevTools console on a page you control.
const a = document.createElement("a");
a.href = "/files/report.pdf";
a.download = "monthly-report.pdf";
a.textContent = "Download monthly report";
document.body.appendChild(a);
a.click();

// Build a CSV in the page and save it without a server hop.
const blob = new Blob(["name,score\nPrince,42"], { type: "text/csv" });
const blobLink = document.createElement("a");
blobLink.href = URL.createObjectURL(blob);
blobLink.download = "scores.csv";
blobLink.click();
URL.revokeObjectURL(blobLink.href);
// Console output: a Save As prompt for monthly-report.pdf, then for scores.csv.

If the click opens the file in the browser instead of saving it, the page is sandboxed or the URL is cross-origin. Drop the iframe sandbox attribute or move the file to the same origin and re-run the test.

Why does the download attribute fail for cross-origin URLs?

The same-origin policy treats a download with a forced filename as a privileged action. A page on one origin should not be able to rewrite a file's name as it lands on the user's disk, since the new name could disguise a malicious payload as a trusted document.

Each browser ships its own enforcement of the rule:

• Chrome and Edge: From Chrome 65 on, the filename hint is silently dropped for cross-origin URLs. The download still happens, but the saved file uses the server's name. Some MIME types are blocked outright in the navigation path.
• Firefox: The attribute is ignored entirely on cross-origin URLs. The link navigates to the resource and the browser falls back to its default content disposition handling.
• Safari: Same as Firefox. The attribute works only on same-origin, blob, and data URLs. A cross-origin link opens the file in a new tab.
• The fix on the server: Send a Content-Disposition: attachment header with a filename parameter on the file's own origin. The header works across origins, across browsers, and inside Internet Explorer 10 and 11.
• The fix in the page: Fetch the cross-origin file with CORS enabled, wrap the response in a Blob, call URL.createObjectURL, and assign the blob URL to an anchor with the download attribute. The blob URL is same-origin to the page.

What are the known issues with the HTML download attribute?

The HTML download attribute is a hint, not a contract. The browser, the user's settings, and the response headers all get a vote, and a page that ignores any one of them ships a broken download button.

• Cross-origin filename is dropped: Chrome saves the file with the server's name, Firefox and Safari ignore the attribute and navigate. The reliable fix is a Content-Disposition: attachment header on the file's own origin.
• Content-Disposition wins ties: A filename parameter in the response header takes priority over the attribute value. If a server sets the header, the page cannot override the saved filename from the client.
• iOS Safari needs a user gesture: Programmatically clicking the anchor during page load is silently ignored. The click has to fire inside a touch or pointer event handler, otherwise the Save dialog never opens.
• Internet Explorer ignores the attribute: IE 5.5 to IE 11 follow the href and open the file in the browser. The fallback is navigator.msSaveOrOpenBlob, which only exists on IE 10 and 11.
• Slashes become underscores: A download value of "reports/2026/q2.pdf" is rewritten to "reports_2026_q2.pdf". Build the path on the server side instead of inside the attribute.
• Sandboxed iframes break the click: An anchor inside an iframe with the sandbox attribute does not trigger a download unless allow-downloads is in the sandbox token list. Chrome 83 added the token; older releases never download from a sandbox.
• Buttons do not work: The attribute is defined only on a and area. A button needs JavaScript that creates a temporary anchor, sets href and download, and calls click on it.

In my experience, the cross-origin filename trap is the one that ships to production unnoticed; a designer tests on localhost where everything is same-origin, the QA pass on a CDN-hosted asset silently saves the wrong filename, and nobody notices until a customer complains.

Citations

All HTML download attribute version numbers and behavior notes in this guide come from these primary sources:

• WHATWG HTML living standard - download attribute: html.spec.whatwg.org/multipage/links.html#downloading-resources
• MDN Web Docs - anchor element download attribute: developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a
• MDN Web Docs - HTMLAnchorElement.download: developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/download
• Chrome Platform Status - block cross-origin download: chromestatus.com/feature/4969697975992320
• Chrome for Developers - downloading resources in HTML5: developer.chrome.com/blog/downloading-resources-in-html5-a-download
• Mozilla Bugzilla - cross-origin download attribute: bugzilla.mozilla.org/show_bug.cgi?id=874009
• WHATWG HTML issue 2562 - cross-origin download: github.com/whatwg/html/issues/2562
• MDN Web Docs - Content-Disposition: developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Disposition
• WHATWG HTML living standard - sandbox allow-downloads: html.spec.whatwg.org/multipage/iframe-embed-object.html#attr-iframe-sandbox
• Microsoft Learn - msSaveOrOpenBlob fallback: learn.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/platform-apis/hh772332
• Wikipedia - HTML5: en.wikipedia.org/wiki/HTML5