Attribut HTML download

L'attribut HTML download indique au navigateur de télécharger la ressource liée en tant que fichier au lieu d'y accéder directement. Par défaut, cliquer sur un lien vers un PDF, une image ou un fichier texte l'ouvre dans le navigateur ; ajouter download force un téléchargement « Enregistrer sous » à la place. Vous l'ajoutez à un lien hypertexte, et vous pouvez lui attribuer une valeur optionnelle pour suggérer un nom de fichier pour le fichier enregistré.

Quand l'utiliser ? Recourez à download lorsque le lien pointe vers un fichier que l'utilisateur doit conserver plutôt que consulter — un rapport PDF, un export CSV généré, une image enregistrée depuis un <canvas>, une archive ZIP, ou toute action de type « enregistrer ce fichier ». Il n'est utilisé que si l'attribut href est défini.

Vous pouvez utiliser l'attribut download sur les éléments suivants : <a> et <area>.

Suggérer un nom de fichier

La valeur de l'attribut spécifie le nom du fichier téléchargé. Le navigateur utilise la valeur exactement telle qu'elle est saisie, sans ajouter automatiquement une extension de fichier — veillez donc à l'inclure vous-même. Si la valeur est omise, le navigateur utilise par défaut le nom de fichier d'origine issu de l'URL (ou un nom déduit de la réponse).

<!-- 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 substitution du nom de fichier est particulièrement pratique lorsque votre serveur stocke des fichiers sous des noms hachés ou cryptiques, mais que vous souhaitez que l'utilisateur reçoive un nom de fichier lisible et convivial.

Syntaxe

<a href="url" download="filename">link text</a>

La valeur filename est facultative. <a href="url" download> fonctionne également et conserve le nom d'origine.

Exemple de l'attribut HTML download utilisé sur l'élément `<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>

Essayez vous-même »

La restriction de même origine

C'est la raison la plus courante pour laquelle download « ne fonctionne pas ». Pour des raisons de sécurité, l'attribut download n'est respecté que pour :

Les URL de même origine — le fichier est servi depuis le même schéma, hôte et port que la page courante.
Les URL blob: — créées en JavaScript avec URL.createObjectURL().
Les URL data: — données en ligne encodées directement dans le href.

Pour une URL d'origine croisée (un fichier hébergé sur un autre domaine), l'attribut est ignoré : le navigateur navigue simplement vers la ressource comme si download n'était pas présent. La substitution du nom de fichier est également ignorée. Ainsi, <a href="https://other-site.com/file.pdf" download="report.pdf"> n'enregistrera pas report.pdf — il ouvre simplement le fichier distant.

Solution de contournement : récupérer le fichier et créer une URL blob

Pour forcer le téléchargement d'un fichier d'origine croisée (en supposant que le serveur distant l'autorise via CORS), récupérez-le en mémoire, enveloppez-le dans une URL blob, et déclenchez un téléchargement avec celle-ci :

<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>

Le serveur distant doit envoyer des en-têtes CORS permissifs (par exemple Access-Control-Allow-Origin: *) pour que le fetch réussisse.

Générer des téléchargements avec des URL `data:`

Comme les URL data: sont de même origine par définition, vous pouvez télécharger du contenu créé entièrement dans le navigateur sans aucun aller-retour vers le serveur — utile pour les exports CSV ou pour enregistrer un dessin <canvas> en tant qu'image :

<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>

Pour les fichiers volumineux, préférez l'approche par URL blob plutôt que les URL data:, car les chaînes data: très longues sont gourmandes en mémoire et certains navigateurs limitent leur longueur.

Utiliser download sur une zone de carte d'image

L'attribut download fonctionne également sur l'élément <area> à l'intérieur d'une carte d'image, de sorte que chaque région cliquable d'une image peut télécharger un fichier différent.

Exemple de l'attribut HTML download utilisé sur l'élément `<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>

Essayez vous-même »

Exercice

Pratique

Que fait l'attribut HTML download ?

Il indique au navigateur de télécharger la ressource liée au lieu d'y accéder directement.Il initialise un compte à rebours avant le début du téléchargement.Lorsqu'une valeur lui est attribuée, il suggère un nom de fichier pour le fichier téléchargé.Il fonctionne sur les URL d'origine croisée de la même façon que sur les URL de même origine.Il déclenche un événement JavaScript 'download' lors du clic.