Which element should a CSS download button use?
An a element, with an href that points to the file and the download attribute. A button element has no URL to save, so it cannot download anything until JavaScript steps in.
That gap shows up in a lot of copy-paste examples. W3Schools’ download button how-to, for one, styles a button with an icon and a hover color, but the markup carries no file at all.
The anchor route also keeps everything in plain HTML, so the download still works when scripts fail to load.
What the download attribute does
Add it and the browser saves the linked URL instead of navigating to it (MDN Web Docs). The WHATWG HTML Living Standard defines the behavior. Safari on iOS 13 finished cross-browser support in September 2019, and the web-features project lists the attribute as Baseline widely available since March 2022.
Leave the attribute without a value and the browser picks a file name itself. The filename in the server’s Content-Disposition header is one source, and the last segment of the URL path is another. The Content-Type header gets a say too, mostly to settle the extension.
Anything on another domain behaves differently (more on that below).
How to set a custom file name
Give the attribute a value and the browser suggests it as the file name.
<a class="btn-download" href="/files/pricing-guide-2026.pdf" download="acme-pricing-guide.pdf">Download the pricing guide</a>
Slashes and backslashes in the value turn into underscores, and the browser adjusts any character the filesystem forbids.
One catch. If the server sends a Content-Disposition header with a filename parameter, that name overrides the one in your markup.
I’d pick the anchor whenever a real URL exists, even for generated files. MDN’s own example saves a canvas as a PNG with an anchor and a data: URL. Its guidance says a hyperlink is for navigating to a real URL, while a button belongs to script-driven actions. A click that calls an API before the file exists is one example.
Core styles that turn an anchor into a button
An anchor looks like a button once it has padding, a solid background, rounded corners and no underline. Add a font weight, a text color and a soft shadow and nobody will guess it started as a link.
- Write the anchor with a class, a real file path in
href and the download attribute. - Strip the link defaults with
text-decoration: none and an explicit color. - Set the shape with
display: inline-flex, padding: 0.75rem 1.5rem and border-radius: 8px. - Give it weight and depth with
font-weight: 600, a background and a soft box-shadow. - Move colors and radius into custom properties so every state reuses them.
:root {
--btn-bg: #0b5fff;
--btn-bg-hover: #0847c4;
--btn-text: #ffffff;
--btn-radius: 8px;
}
.btn-download {
display: inline-flex;
align-items: center;
gap: 0.5rem;
padding: 0.75rem 1.5rem;
border-radius: var(--btn-radius);
background: var(--btn-bg);
color: var(--btn-text);
font-weight: 600;
text-decoration: none;
box-shadow: 0 2px 6px rgba(0, 0, 0, 0.2);
}
inline-flex beats inline-block here. It centers an icon and label on one axis and spaces them with gap, so no margin hacks.
Radius depends on context. Somewhere between 4px and 8px reads as a standard interface button. 999px gives you a pill.
If you’d rather start from something visual, a CSS button generator outputs the same declarations. Paste its values into the custom properties above.
A gradient background works too. A CSS gradient generator speeds up the color picking, but checking the lightest stop against the label color is still on you.
How to style hover, focus-visible, active and disabled states
Hover, keyboard focus, press and disabled each get a selector of their own (:hover, :focus-visible, :active and [aria-disabled="true"]). Each one changes a property or two, so the base class stays untouched.
| State | Selector | Typical change |
|---|
| Hover | :hover | Darker background |
| Keyboard focus | :focus-visible | Outline with offset |
| Pressed | :active | 1px shift or deeper shade |
| Disabled | [aria-disabled="true"] | Reduced opacity, no pointer cursor |
Hover is the easy one. Swap the background to the darker custom property, and if a plain color change feels flat, browse a longer list of button hover effects.
.btn-download:hover { background: var(--btn-bg-hover); }
.btn-download:active { transform: translateY(1px); }
Why :focus-visible beats :focus
MDN’s :focus-visible reference points to WCAG 2.1 SC 1.4.11, which sets the floor for a visual focus indicator at 3:1 contrast. It also warns that removing focus styles makes keyboard navigation inaccessible for sighted users.
:focus-visible matches only when the browser decides the user needs to see where focus sits. A mouse click on the button stays clean, while tabbing to it shows the ring.
.btn-download:focus-visible {
outline: 3px solid #111111;
outline-offset: 3px;
}
Pick an outline color that holds 3:1 against the page background, not just against the button. The offset leaves a gap, so the page color is what the ring sits on.
MDN lists :focus-visible as Baseline widely available, with support across browsers since March 2022. A :focus fallback now only matters for very old browsers.
Disabling a link styled as a button
An anchor has no disabled attribute, so a disabled download link takes ARIA plus some code of your own. Add aria-disabled="true" so assistive technology announces the state. The browser draws no disabled look for it, which means you style [aria-disabled="true"] yourself, and the click gets blocked in JavaScript.
That state comes from ARIA, and it only changes what screen readers announce. The link stays focusable and clickable.
[aria-disabled="true"] {
opacity: 0.5;
cursor: not-allowed;
}
pointer-events: none stops mouse clicks but not keyboard activation, so pair it with a click handler that calls preventDefault(). If the disabled button stays in the tab order, keep its text legible, since MDN notes that such styling may still need to pass color contrast requirements.
The blunt alternative is dropping the href. Without it the element is no longer a hyperlink (MDN lists its implicit role as generic), so no download starts.
How to add a download icon, file type and file size
Inline SVG is the icon I’d pick. It takes the text color through currentColor, so hover and disabled colors follow along automatically, and nothing extra loads.
Icon fonts are the usual choice in tutorials, Font Awesome especially, but that loads a whole font file for one glyph. A background image can’t change color with the text, so each state needs its own file.
Paste the markup straight into the anchor, as explained in this walkthrough of SVG in HTML.
<a class="btn-download" href="/files/pricing-guide-2026.pdf" download>
<svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
<path d="M12 16 6 10h4V3h4v7h4l-6 6zm-8 3h16v2H4z"/>
</svg>
Download the pricing guide (PDF, 2.4 MB)
</a>
The gap from the base style spaces the icon from the label, so the SVG needs no margin. Alignment comes from align-items: center on the anchor.
The icon is decorative here because the visible label already names the action, so aria-hidden="true" keeps screen readers from reading it twice. The same logic for other graphics is covered in this piece on accessible SVG files.
If the icon is the only sign of the file type, give it a text alternative instead. MDN’s anchor reference does this with an alt on a file-type icon.
Showing file type and file size
GOV.UK’s attachment link component prints file details in brackets after the link text, as in “Temporary snow ploughs: guidance note (PDF, 19.5 KB, 1 page)”. The GOV.UK publishing design guide requires that a link meant for downloading a file, rather than opening a page, specify the file type and size.
The type is just the format name, such as PDF, ZIP or MP3, and the size goes in KB or MB, like the 19.5 KB in the GOV.UK example. Put both inside the link text so screen readers announce them together with the button name.
GOV.UK’s component takes the size and content type as parameters instead of hand-typed text, so the label follows the file. The Scottish Government Design System goes further and uses ARIA attributes so VoiceOver announces type and size together, for example a 44 page PDF at 7.2 megabytes.
Generate the label from the file itself at build time. A typed-in “2.4 MB” goes stale the day someone replaces the PDF.
How to animate a download button with CSS
A transition on background and transform covers hover and press feedback. Keyframes take over for loading and success states, which a transition cannot script.
Bootstrap 5.3 sets its button transition to 0.15 seconds with ease-in-out across color, background-color, border-color and box-shadow (Bootstrap documentation). Anything much slower reads as lag on a control people click once.
.btn-download {
transition: background-color 0.15s ease-in-out,
transform 0.15s ease-in-out;
}
Add it to the base class. The :hover and :active rules already change the two properties it watches.
Keyframes for the arrow and the success state
A looping arrow needs keyframes, because a transition only moves between two states. This guide to CSS keyframes covers the syntax, and the rule itself is short.
@keyframes nudge {
0%, 100% { transform: translateY(0); }
50% { transform: translateY(3px); }
}
.btn-download:hover svg {
animation: nudge 0.6s ease-in-out 2;
}
Why a CSS progress bar can only be decoration
CSS can run a bar on a fixed timer after the click, and it can swap the label to “Preparing” and back, much like the CSS loaders people already use for waiting states. It cannot read how many bytes the browser has saved, and it has no idea whether the download finished or failed.
Vaadin’s download documentation notes that the browser shows no progress percentage when the content length is not known in advance. Real progress needs a streamed fetch response and a Content-Length header, the route the hx-download extension in htmx 4 takes with its progress events.
If the server needs time to generate the file, a CSS progress bar can show that preparation is under way. Label it that way, so the bar never promises a transfer percentage it cannot measure.
Pure CSS state tricks carry a cost too. A button driven by the checkbox hack is a label, and one driven by :target is a hash link, so neither points at a file.
Respecting reduced motion
MDN lists the prefers-reduced-motion media feature as Baseline widely available, with support across browsers since January 2020. It exists for people who set their device to minimize non-essential motion, and a nudging arrow counts as non-essential.
@media (prefers-reduced-motion: reduce) {
.btn-download,
.btn-download svg,
.btn-download:hover svg {
transition: none;
animation: none;
}
}
Place the block after the animation rules. Where two rules have equal specificity, the later one in source order wins (MDN). The hover rule above is more specific than .btn-download svg, which is why the block lists .btn-download:hover svg as well.
When the download attribute does not work
A file on another origin, a conflicting Content-Disposition header, a browser without support and a cross-origin fetch without CORS headers will each break it. The table shows what the browser does in every case and how to fix it.
| Condition | What happens | Fix |
|---|
| File on another origin (CDN host, subdomain, other port) | Attribute ignored, normal navigation | Serve from your origin or send Content-Disposition: attachment |
Same-origin file with an inline header | Attribute wins in current Chrome and Firefox (Firefox 82 and later) | Send attachment and remove the doubt |
| Opera Mini | Attribute unsupported in every version (Can I use) | Accept the plain-link fallback |
| Fetch and blob from another host | Blocked without CORS headers | Add Access-Control-Allow-Origin on the file host |
Cross-origin files, engine by engine
Chrome 65, in beta from February 2018, made Blink ignore the attribute on cross-origin anchors. Chrome’s developer blog gives the reason: it closes a route for leaking cross-origin information through user actions.
WebKit’s changeset 206478 ignores the attribute the same way, and its commit message notes that this matches Firefox.
Before shipping, run the button through the routine in this guide to cross-browser compatibility. Chrome, Firefox and Safari are the minimum set.
Fixing it on the server
Fix the headers before reaching for scripts. MDN notes that a target page can still instruct a download through Content-Disposition, even when the attribute is ignored.
Content-Disposition: attachment; filename="pricing-guide-2026.pdf"
One case used to differ by browser. Older MDN notes said Firefox before version 82 let an inline header win over the attribute, while Chrome honored the attribute. MDN’s current text says an honored attribute overrides inline.
Testing both browsers settles it for your files. An attachment header removes the question.
The fetch and blob workaround
When the server headers are out of reach, JavaScript can fetch the file and hand the browser a blob: URL that sits on the page’s own origin. It only works if the file host sends CORS headers. The whole file also loads into memory before saving, so keep it to small files, and if scripts fail the link falls back to a plain navigation.
const link = document.querySelector(".btn-download");
link.addEventListener("click", async (event) => {
event.preventDefault();
const response = await fetch(link.href);
const blob = await response.blob();
const url = URL.createObjectURL(blob);
const temp = document.createElement("a");
temp.href = url;
temp.download = "pricing-guide-2026.pdf";
temp.click();
setTimeout(() => URL.revokeObjectURL(url), 1000);
});
What does an accessible download button need?
The checks come from the WCAG 2.2 rules behind web accessibility, and most of them take one line of CSS. The button needs a target of at least 24 by 24 CSS pixels, 4.5:1 contrast for the label and a visible focus indicator. The link text has to name the file as well.
On the numbers, W3C sets the minimum target size at 24 by 24 CSS pixels for Level AA (SC 2.5.8), while MDN, citing SC 2.5.5, recommends 44 by 44 CSS pixels at Level AAA. Normal text needs 4.5:1 contrast at Level AA (W3C, SC 1.4.3).
Target size and spacing
Padding sets the target, not the icon. The base style from earlier lands at roughly 42 to 48 pixels tall depending on the font and its line height, so it clears the 24 pixel minimum and sits near the 44 pixel recommendation.
.btn-download {
min-height: 44px;
}
W3C lists min-height and min-width on the target container as a sufficient technique (C42). Stacked download buttons need a gap between them as well, because W3C’s own toolbar example shows small targets passing with space around them and failing when packed together.
Contrast in every state
W3C’s guidance applies the ratio to text shown on hover or keyboard focus too, so the darker hover background must still hold 4.5:1 against the label. Checking takes seconds once you know how color contrast is calculated.
The sources split on disabled buttons. W3C exempts text on inactive controls, but MDN still advises legible styling when an aria-disabled control stays in the tab order. I’d treat the exemption as a floor and keep the disabled label readable.
Accessible name
Say what the file is. “Download the 2026 pricing guide” works, “Click here” doesn’t.
Each button on a page needs its own name, since screen reader link lists show names out of context. Strong link text helps sighted users too, because they scan links the same way (MDN).
Plain CSS, Bootstrap or Tailwind: which fits a download button?
Plain CSS fits a single button. Bootstrap or Tailwind win only when the site already runs on one of them.
| Approach | Setup | Control | Main drawback |
|---|
| Plain CSS | One class, no dependency | Full | Every state is yours to write |
| Bootstrap 5.3 | btn btn-primary on the anchor | CSS variables on .btn | Pulls in a framework for one control |
| Tailwind | Utility classes on the anchor | Per-utility variants | Long class strings in the markup |
Bootstrap
The Bootstrap button classes work on a elements, so the anchor from earlier takes them unchanged. Bootstrap asks for role="button" only when an anchor triggers in-page behavior, and a link to a file is navigation, so the attribute stays off.
Disabling gets awkward. Bootstrap’s docs say a disabled anchor button should drop the href. If the href must stay, add tabindex="-1" and custom JavaScript, because pointer-events: none leaves keyboard activation untouched.
<a class="btn btn-primary" href="/files/pricing-guide-2026.pdf" download>Download the pricing guide</a>
Tailwind
<a class="inline-flex items-center gap-2 rounded-lg bg-blue-600 px-6 py-3 font-semibold text-white hover:bg-blue-700 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600" href="/files/pricing-guide-2026.pdf" download>Download the pricing guide</a>
Tailwind’s documentation applies every utility conditionally through a variant prefix, and it includes hover, focus, active and focus-visible variants. The Tailwind button patterns in that style stack on top of the same anchor.
The cost is the class string, which grows with every state you add.
Reuse the framework’s button class if the site already loads one. Loading Bootstrap for a single download anchor is the wrong trade.
CSS Download Button FAQ
How do you make a download button full width on mobile?
Set display: flex inside a max-width media query, so the anchor fills its container on phones and keeps its inline-flex size elsewhere. Leave the padding from the base style alone, because it holds the target size.
Which color should a download button use?
Use the site’s primary action color, provided the label passes the contrast check covered earlier. Bootstrap’s documentation adds a warning that color alone is not conveyed to screen reader users, so the label text must name the action.
How do you add a download button in WordPress or Divi without writing CSS?
In WordPress, the File block has a Show download button toggle in its settings, and no CSS is needed.
Divi’s Button module links to a file, but adding the download attribute takes a jQuery snippet, per Elegant Themes’ Divi 4 tutorial. A third-party module such as Divi Supreme offers a Download button type instead, in its Pro version.
Should a download button open in a new tab?
No. The download attribute makes the browser treat the URL as a download, so a new tab adds nothing. If a link does open a new tab, the link text should say so, as MDN advises.
Can CSS or HTML force a Save As dialog?
No. MDN states that the browser, user settings and other factors decide whether the user is prompted, the file saves automatically, or it opens in an application or the browser. A Content-Disposition: attachment header set on the server triggers a download in all major browsers, though whether a dialog appears still depends on browser settings.
What to Check Before Shipping a CSS Download Button
Check the button on the production host first, then by keyboard, then on a phone.
Localhost hides cross-origin failures, which is why production goes first. The keyboard pass should cover every state, focus included. On the phone, look at target size and tap spacing.
The order follows where failures hide. A local server delivers the file from the page’s own origin, so the button downloads in development and opens a page once the file moves to a CDN, with every style intact.
Moving the file onto the page’s origin removes that failure at the cost of serving the traffic from the main host. The fetch and blob route avoids that cost but holds the whole file in memory.
This advice was verified on October 27, 2026, against MDN’s anchor element page, last modified October 12, 2026. A browser that lifts the same-origin restriction would remove the first check.