Back to HTML

Download Links and the download Attribute

Coding Tutorials Team 14 July 2026

By default, a link to a file lets the browser decide what to do with it. An image displays, a document may open in a built in viewer, and an unrecognised format downloads. The download attribute overrides that and asks for a download regardless.

The basic use

<a href="/files/report.pdf" download>Download the report</a>

Written as a bare attribute, this downloads the file under its existing name. It is the simplest form and covers most cases.

Renaming the downloaded file

Giving the attribute a value sets the filename the user receives, which does not have to match the name on the server.

<a href="/files/rpt-2026-q2-final-v3.pdf" download="Q2-Report.pdf">Download</a>

This is genuinely useful, because server side filenames are often generated, hashed or full of internal versioning that means nothing to the person saving them. A clean name is a small courtesy that makes the file findable later.

The browser may still adjust what you supply, appending a number if a file of that name already exists and stripping characters that are not permitted on the operating system.

The same origin restriction

This is the part that catches people out. The download attribute only works for files served from your own origin, meaning the same scheme, domain and port.

Point it at a file on another domain and the attribute is ignored entirely. The browser navigates to the file instead, and it will be displayed or handled however that site's headers dictate. Nothing warns you, so the link appears broken only in the sense that it does something different from what you intended.

The restriction exists to stop a site silently saving files from elsewhere onto a visitor's machine under a name of its choosing, which would be an obvious avenue for disguising one kind of file as another. If you need to offer a third party file as a download, the file has to be served through your own domain, either by hosting a copy or by proxying it.

The server can force it too

The other mechanism is a response header instructing the browser to treat the response as an attachment, optionally naming the file. Because it is set server side it works regardless of origin and regardless of how the link was written.

Use the header when the behaviour must be guaranteed, such as for a generated export or a file behind an access check. Use the attribute when it is a convenience on a static file. The two can coexist without conflict.

Tell the user what they are getting

A link that starts an unexpected download is a poor experience, especially on a metered mobile connection. The link text should make the outcome obvious before the click, and the useful details are the format and the size.

<a href="/files/guide.pdf" download> Download the CSS guide (PDF, 2.4 MB) </a>

Including the size lets someone on a poor connection make an informed decision. Including the format sets expectations about what will open it. Both belong in the link text rather than in a tooltip, since a tooltip is unavailable on touch and unreliable for screen readers.

If you use an icon to indicate a download, treat it as decoration and keep the information in the text. An icon alone is a convention that does not exist for anyone who cannot see it.

Opening in the browser instead

For formats browsers display well, particularly documents and images, consider whether a download is what the user wants. Many people prefer to look at a document first and save it only if it turns out to be useful, and forcing a download removes that step from them.

A reasonable compromise is to let the file open normally and provide a separate, clearly labelled download control beside it. That way the default action is the low commitment one and saving remains one click away for anyone who wants it.

Downloads and analytics

A file download is not a page view, so it will not appear in analytics automatically. Tracking them normally requires an event fired on click, which is worth setting up if the files matter to you, since download counts are often a better measure of whether a resource is useful than the views of the page hosting it.

Large files and alternatives

For anything substantial, consider whether a download is the right delivery at all. A long document might be better as a web page, which is searchable, linkable, readable on any device and does not require an application to open. Offering both is common, and the web version is usually the one that earns search visibility while the file serves people who need it offline.