download

Overview

The download attribute on <a> and <area> elements tells the browser to download the linked resource as a file instead of navigating to it. Without this attribute, the browser decides based on the MIME type — PDFs might open in a viewer, images display inline, and HTML navigates.

When a value is provided, it serves as the suggested filename for the download. The user can still change the name in the save dialog.

Values

Applies to: <a>, <area>

Cross-Origin Limitation

For security reasons, the download attribute is ignored on cross-origin URLs. If the link points to a different origin, the browser navigates to the URL instead of downloading. This prevents a malicious page from silently downloading files from other domains onto the user's device.

To enable cross-origin downloads, the server must set the Content-Disposition: attachment HTTP header. This is a server-side solution that works regardless of the download attribute.

Generated Content with Blob URLs

The most powerful use of download is with Blob URLs for client-generated content. Create the data in JavaScript, wrap it in a Blob, generate a temporary URL, and trigger a download — no server round-trip required.

Canvas to Image Download

Combine download with canvas.toDataURL() to let users save canvas drawings as image files.

Filename Behavior

• If download has no value, the browser derives the filename from the URL path (e.g. /files/report.pdf saves as report.pdf).
• If a value is provided, it overrides the URL-derived name but the server's Content-Disposition header takes priority over both.
• The browser may sanitize the suggested filename, stripping path separators and other unsafe characters.
• For Blob URLs, there is no URL-derived name, so providing a download value is essential.

Security Considerations

The cross-origin restriction exists to prevent drive-by downloads from untrusted origins. Even for same-origin resources, browsers may prompt the user before downloading executable file types (.exe, .bat, .sh). Some browsers block downloads entirely from sandboxed iframes unless allow-downloads is present.

Limitations

• Cross-origin URLs ignored: The attribute has no effect when the href points to a different origin. Use server-side Content-Disposition headers instead.
• No progress feedback: There is no built-in way to show download progress for download-triggered downloads. Large files start downloading silently.
• Content-Disposition wins: If the server sends a Content-Disposition header, its filename takes priority over the download attribute value.
• Data URL size limits: Very large data URLs may fail in some browsers. Prefer Blob URLs for generated content over a few megabytes.
• Mobile behavior varies: Some mobile browsers open files in a viewer app rather than saving to the filesystem, even with the download attribute.