download Attribute

Learn how to use the HTML download attribute to force browsers to save files instead of opening them, and understand its critical security limitations.

What it is

The download attribute is a boolean attribute added to anchor (<a>) elements. When present, it instructs the browser to download the linked resource rather than navigate to it or display it inline (like rendering an image or PDF). You can optionally provide a value to suggest a specific filename for the saved file.

Mental Model: Think of it as a polite request to the browser saying, "Don't show this; save it." However, browsers enforce strict security rules regarding where that file comes from.

Why it matters

• User Experience: Prevents unexpected navigation away from your site when users click on assets like PDFs or images.
• Filename Control: Allows you to rename generic server filenames (e.g., doc123.pdf) to user-friendly names (e.g., Invoice_2024.pdf).
• Asset Distribution: Simplifies providing downloadable resources without requiring complex server-side headers for simple static sites.
• Security Awareness: Understanding its limits helps developers avoid false assumptions about cross-origin downloads.

Syntax or steps

Add the download attribute to an anchor tag. The syntax is straightforward:

<a href="path/to/file.ext" download="desired_filename.ext">Link Text</a>

If you omit the value (just download), the browser uses the original filename from the URL. If you include a value, the browser attempts to use that name, sanitizing invalid characters automatically.

Example

This example demonstrates downloading a local text file with a custom name versus using the default name.

<!DOCTYPE html>
<html>
<body>
  <p><!-- Forces download as 'my-report.txt' -->
  <a href="report.txt" download="my-report.txt">Download Report (Custom Name)</a></p>

  <p><!-- Forces download as 'report.txt' (original name) -->
  <a href="report.txt" download>Download Report (Default Name)</a></p>
</body>
</html>

Part-by-part explanation:

• <a href="report.txt">: Specifies the target file location.
• download="my-report.txt": Instructs the browser to save the file and suggests the filename my-report.txt.
• download (no value): Instructs the browser to save the file but keeps the original filename report.txt.

Common mistakes

• Assuming Cross-Origin Works: The download attribute is ignored if the link points to a different domain (cross-origin). For example, linking to https://other-site.com/file.pdf will not trigger a forced download in most modern browsers due to security policies.
• Invalid Filenames: Providing filenames with illegal characters (like /, \, or :) may cause the browser to ignore the suggested name or sanitize it unexpectedly.
• Expecting Server-Side Enforcement: This is a client-side hint. Users can still configure their browsers to open files directly, ignoring the attribute.
• Using on Non-Anchor Elements: The attribute only works on <a> tags. Adding it to buttons or divs has no effect.

When to use it

Compare download with HTTP Content-Disposition headers.

Use the HTML attribute for simple, same-origin static files. Use server headers for robust, cross-origin, or dynamic scenarios.

Practice

Guided Exercise: Create an HTML page with a link to a local image named logo.png. Add the download attribute with the value company-logo.png. Test it by clicking the link.

Challenge: Try adding the download attribute to a link pointing to https://www.wikipedia.org. Observe what happens. Why did it fail?

Hint: It fails because Wikipedia is a different origin. Browsers block cross-origin downloads via this attribute to prevent malicious redirection or data theft.

Quick check

Question: Will the download attribute work if I link to a PDF hosted on a CDN with a different domain?

Answer: No. Modern browsers ignore the download attribute for cross-origin URLs for security reasons. You must use server-side headers or JavaScript Blob methods for cross-origin downloads.

Summary

The download attribute provides a simple way to force file saves and rename downloads for same-origin resources. Always remember its security limitation: it does not work across different domains, making server-side configuration necessary for more complex distribution needs.