Atributo download do HTML
O atributo download do HTML especifica que o destino será baixado ao clicar no hiperlink. Saiba em quais elementos ele pode ser usado.
O atributo download do HTML instrui o navegador a baixar o recurso vinculado como um arquivo em vez de navegar até ele. Por padrão, clicar em um link para um PDF, imagem ou arquivo de texto o abre no navegador; adicionar download força um download do tipo "Salvar como" em vez disso. Você o adiciona a um hiperlink e pode, opcionalmente, atribuir um valor para sugerir um nome de arquivo para o arquivo salvo.
Quando usá-lo? Use download quando o link aponta para um arquivo que o usuário deve manter em vez de visualizar — um relatório em PDF, uma exportação de CSV gerada, uma imagem salva de um <canvas>, um arquivo ZIP ou qualquer ação do tipo "salvar isto". Ele só é utilizado se o atributo href estiver definido.
Você pode usar o atributo download nos seguintes elementos: <a> e <area>.
Sugerindo um nome de arquivo
O valor do atributo especifica o nome do arquivo baixado. O navegador usa o valor exatamente como digitado, sem adicionar automaticamente uma extensão de arquivo — portanto, inclua a extensão você mesmo. Se o valor for omitido, o navegador recorre ao nome de arquivo original da URL (ou um inferido a partir da resposta).
<!-- Saves with the server's original filename -->
<a href="/files/2024-q4-9f8a7b.pdf" download>Download report</a>
<!-- Overrides the filename: saves as "report.pdf" -->
<a href="/files/2024-q4-9f8a7b.pdf" download="report.pdf">Download report</a>A substituição do nome do arquivo é especialmente útil quando o servidor armazena arquivos com nomes hash ou enigmáticos, mas você deseja que o usuário receba um nome de arquivo amigável e legível.
Sintaxe
<a href="url" download="filename">link text</a>O valor filename é opcional. <a href="url" download> também funciona e mantém o nome original.
Exemplo do atributo download do HTML usado no elemento <a>:
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
<h1>Click on the logo to download it:</h1>
<p>
<a href="/uploads/media/default/0001/01/0710cad7a1017902166203def268a0df2a5fd545.png" download="w3docs-logo.png">
<img src="/uploads/media/default/0001/01/0710cad7a1017902166203def268a0df2a5fd545.png" alt="W3Docs" width="190" height="45" />
</a>
</p>
</body>
</html>A restrição de mesma origem
Esse é o motivo mais comum pelo qual o download "não funciona". Por razões de segurança, o atributo download só é respeitado para:
- URLs de mesma origem — o arquivo é servido a partir do mesmo esquema, host e porta que a página atual.
- URLs
blob:— criadas em JavaScript comURL.createObjectURL(). - URLs
data:— dados inline codificados diretamente nohref.
Para uma URL de origem diferente (um arquivo hospedado em outro domínio), o atributo é ignorado: o navegador simplesmente navega até o recurso como se download não estivesse lá. A substituição do nome do arquivo também é descartada. Portanto, <a href="https://other-site.com/file.pdf" download="report.pdf"> não salvará report.pdf — apenas abre o arquivo remoto.
Solução alternativa: buscar o arquivo e criar uma URL blob
Para forçar o download de um arquivo de origem diferente (supondo que o servidor remoto permita via CORS), busque-o na memória, envolva-o em uma URL blob e acione um download com ela:
<button id="dl">Download remote PDF</button>
<script>
document.getElementById('dl').addEventListener('click', async () => {
const response = await fetch('https://other-site.com/file.pdf');
const blob = await response.blob();
const blobUrl = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = blobUrl;
a.download = 'report.pdf'; // honored, because blob: is allowed
document.body.appendChild(a);
a.click();
a.remove();
URL.revokeObjectURL(blobUrl); // free the memory
});
</script>O servidor remoto deve enviar cabeçalhos CORS permissivos (por exemplo, Access-Control-Allow-Origin: *) para que o fetch seja bem-sucedido.
Gerando downloads com URLs data:
Como URLs data: são de mesma origem por definição, você pode baixar conteúdo criado inteiramente no navegador sem nenhuma ida ao servidor — útil para exportações de CSV ou para salvar um desenho de <canvas> como imagem:
<a id="csv" download="export.csv">Download CSV</a>
<canvas id="c" width="100" height="100"></canvas>
<a id="img" download="drawing.png">Save drawing</a>
<script>
// 1. A generated CSV file
const csv = 'Name,Score\nAlice,90\nBob,85';
document.getElementById('csv').href =
'data:text/csv;charset=utf-8,' + encodeURIComponent(csv);
// 2. A canvas saved as a PNG (toDataURL returns a data: URL)
const canvas = document.getElementById('c');
document.getElementById('img').href = canvas.toDataURL('image/png');
</script>Para arquivos maiores, prefira a abordagem com URL blob em vez de URLs data:, pois strings data: muito longas consomem muita memória e alguns navegadores limitam seu comprimento.
Usando download em uma área de mapa de imagem
O atributo download também funciona no elemento <area> dentro de um mapa de imagem, de modo que regiões clicáveis individuais de uma imagem podem, cada uma, baixar um arquivo diferente.
Exemplo do atributo download do HTML usado no elemento <area>:
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
<p>Click on one of the HTML, CSS or PHP logo and download it:</p>
<img src="/uploads/media/news_gallery/0001/01/thumb_316_news_gallery_list.jpeg" width="250" height="150" alt="block" usemap="#blockmap" />
<map name="blockmap">
<area shape="circle" coords="50,32,25" alt="html" href="/uploads/media/book_gallery/0001/01/d450f0358f947dffb3af91195c3002600d74101b.png" download />
<area shape="circle" coords="218,115,25" alt="css" href="/uploads/media/book_gallery/0001/01/25521e981b34da57c8f51baddc5b76351b855818.png" download />
<area shape="circle" coords="195,32,28" alt="php" href="/uploads/media/book_gallery/0001/01/4bbee6698c4884f25c46010d61b658dd62d2c04f.png" download />
</map>
</body>
</html>