Atributo download de HTML
El atributo download de HTML indica al navegador que descargue el recurso enlazado como archivo. Descubre en qué elementos se puede usar.
El atributo download de HTML indica al navegador que descargue el recurso enlazado como un archivo en lugar de navegar hacia él. Por defecto, al hacer clic en un enlace a un PDF, imagen o archivo de texto, este se abre en el navegador; añadir download fuerza una descarga de tipo "Guardar como". Se agrega a un hipervínculo y, opcionalmente, se le puede asignar un valor para sugerir un nombre de archivo para el archivo guardado.
¿Cuándo utilizarlo? Usa download cuando el enlace apunta a un archivo que el usuario debe guardar en lugar de visualizar — un informe PDF, una exportación CSV generada, una imagen guardada desde un <canvas>, un archivo ZIP o cualquier acción de "guardar esto". Solo se usa si el atributo href está definido.
Puedes usar el atributo download en los siguientes elementos: <a> y <area>.
Sugerir un nombre de archivo
El valor del atributo especifica el nombre del archivo descargado. El navegador usa el valor exactamente tal como se escribió, sin añadir automáticamente una extensión de archivo, por lo que debes incluir la extensión tú mismo. Si se omite el valor, el navegador recurre al nombre de archivo original de la URL (o uno inferido de la respuesta).
<!-- 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>La sustitución del nombre de archivo es especialmente útil cuando el servidor almacena archivos con nombres hash o crípticos, pero quieres que el usuario reciba un nombre de archivo amigable y legible.
Sintaxis
<a href="url" download="filename">link text</a>El valor filename es opcional. <a href="url" download> también funciona y conserva el nombre original.
Ejemplo del atributo download de HTML usado en el 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>La restricción de mismo origen
Esta es la razón más común por la que download "no funciona". Por razones de seguridad, el atributo download solo se respeta para:
- URLs de mismo origen — el archivo se sirve desde el mismo esquema, host y puerto que la página actual.
- URLs
blob:— creadas en JavaScript conURL.createObjectURL(). - URLs
data:— datos en línea codificados directamente en elhref.
Para una URL de origen cruzado (un archivo alojado en otro dominio), el atributo se ignora: el navegador simplemente navega al recurso como si download no estuviera presente. La sustitución del nombre de archivo también se descarta. Así que <a href="https://other-site.com/file.pdf" download="report.pdf"> no guardará report.pdf — simplemente abrirá el archivo remoto.
Solución alternativa: obtener el archivo y crear una URL blob
Para forzar la descarga de un archivo de origen cruzado (suponiendo que el servidor remoto lo permita mediante CORS), obtenlo en memoria, envuélvelo en una URL blob y activa la descarga con ella:
<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>El servidor remoto debe enviar encabezados CORS permisivos (por ejemplo Access-Control-Allow-Origin: *) para que el fetch tenga éxito.
Generar descargas con URLs data:
Dado que las URLs data: son de mismo origen por definición, puedes descargar contenido creado completamente en el navegador sin ningún viaje al servidor — útil para exportaciones CSV o para guardar un dibujo de <canvas> como imagen:
<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 archivos más grandes, prefiere el enfoque de URL blob en lugar de URLs data:, ya que las cadenas data: muy largas consumen mucha memoria y algunos navegadores limitan su longitud.
Usar download en un área de mapa de imagen
El atributo download también funciona en el elemento <area> dentro de un mapa de imagen, por lo que cada región clicable individual de una imagen puede descargar un archivo diferente.
Ejemplo del atributo download de HTML usado en el 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>