HTMLImageElement - Les API Web | MDN

Basculer la barre latérale

Thème

Automatique
Clair
Sombre

Français

Se souvenir de la langue En savoir plus

HTMLImageElement

Baseline Large disponibilité *

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis juillet 2015.

* Certaines parties de cette fonctionnalité peuvent bénéficier de prise en charge variables.

L'interface HTMLImageElement représente un élément HTML <img>, fournissant les propriétés et méthodes utilisées pour manipuler les éléments image.

EventTarget Node Element HTMLElement HTMLImageElement

Dans cet article

Constructeur

Image()

Le constructeur Image() crée et retourne un nouvel objet HTMLImageElement représentant un élément HTML <img> qui n'est pas attaché à un arbre DOM. Il accepte des paramètres optionnels de largeur et de hauteur. Appelé sans paramètre, new Image() est équivalent à document.createElement('img').

Propriétés d'instance

Hérite des propriétés de son parent, HTMLElement.

HTMLImageElement.alt

Une chaîne de caractères qui reflète l'attribut HTML alt, indiquant le contenu de remplacement à afficher si l'image n'a pas été chargée.

HTMLImageElement.attributionSrc Contexte sécurisé

Permet d'obtenir ou de définir l'attribut attributionsrc sur un élément <img> de façon programmatique, reflétant la valeur de cet attribut. attributionsrc indique que le navigateur doit envoyer un en-tête Attribution-Reporting-Eligible avec la requête d'image. Côté serveur, cela sert à déclencher l'envoi d'un en-tête Attribution-Reporting-Register-Source ou Attribution-Reporting-Register-Trigger dans la réponse, afin d'enregistrer une source d'attribution ou un déclencheur d'attribution.

HTMLImageElement.complete Lecture seule

Retourne une valeur booléenne à true si le navigateur a fini de récupérer l'image, que ce soit avec succès ou non. Cela vaut aussi true si l'image n'a pas de valeur src indiquant une image à charger.

HTMLImageElement.crossOrigin

Une chaîne de caractères indiquant le paramétrage CORS pour cet élément image. Voir les attributs de paramétrage du CORS pour plus de détails. Peut valoir null si CORS n'est pas utilisé.

HTMLImageElement.currentSrc Lecture seule

Retourne une chaîne de caractères représentant l'URL depuis laquelle l'image actuellement affichée a été chargée. Cette valeur peut changer si l'image est modifiée en fonction des conditions, par exemple avec des requêtes média.

HTMLImageElement.decoding

Une chaîne de caractères optionnelle indiquant une préférence sur la façon dont le navigateur doit décoder l'image. Les valeurs possibles sont : sync (décodage synchrone), async (décodage asynchrone), ou auto (pas de préférence, valeur par défaut). Voir la page decoding pour plus de détails.

HTMLImageElement.fetchPriority

Une chaîne de caractères optionnelle indiquant une préférence sur la priorité de récupération de l'image par rapport aux autres images. Les valeurs possibles sont : high (priorité haute), low (priorité basse), ou auto (pas de préférence, valeur par défaut).

HTMLImageElement.height

Un entier qui reflète l'attribut HTML height, indiquant la hauteur affichée de l'image en pixels CSS.

HTMLImageElement.isMap

Un booléen qui reflète l'attribut HTML ismap, indiquant que l'image fait partie d'une carte côté serveur. Différent d'une carte côté client, qui utilise un élément <img> et un <map> contenant des <area> pour les zones cliquables. L'image doit être contenue dans un élément <a> ; voir la page ismap pour plus de détails.

HTMLImageElement.loading

Une chaîne de caractères indiquant si le navigateur doit charger l'image immédiatement (eager) ou lorsqu'elle est nécessaire (lazy).

HTMLImageElement.naturalHeight Lecture seule

Retourne un entier représentant la hauteur intrinsèque de l'image en pixels CSS, si disponible ; sinon, retourne 0. C'est la hauteur que l'image aurait si elle était affichée à sa taille naturelle.

HTMLImageElement.naturalWidth Lecture seule

Un entier représentant la largeur intrinsèque de l'image en pixels CSS, si disponible ; sinon, retourne 0. C'est la largeur que l'image aurait si elle était affichée à sa taille naturelle.

HTMLImageElement.referrerPolicy

Une chaîne de caractères qui reflète l'attribut HTML referrerpolicy, indiquant à l'agent utilisateur quelle politique de référent utiliser pour récupérer l'image. Voir l'article pour les valeurs possibles.

HTMLImageElement.sizes

Une chaîne de caractères reflétant l'attribut HTML sizes. Cette chaîne de caractères définit une liste de tailles conditionnelles séparées par des virgules pour l'image ; c'est-à-dire, pour une taille de zone d'affichage donnée, une taille d'image particulière est utilisée. Voir la documentation de sizes pour le format de cette chaîne.

HTMLImageElement.src

Une chaîne de caractères qui reflète l'attribut HTML src, contenant l'URL complète de l'image (y compris la base). Vous pouvez charger une autre image en modifiant l'URL dans l'attribut src.

HTMLImageElement.srcset

Une chaîne de caractères reflétant l'attribut HTML srcset. Cela définit une liste d'images candidates, séparées par des virgules. Chaque image candidate est une URL suivie d'un espace, puis d'une chaîne indiquant la taille de l'image (largeur ou multiple de taille). Voir la page srcset pour le format détaillé.

HTMLImageElement.useMap

Une chaîne de caractères reflétant l'attribut HTML usemap, contenant l'URL locale de la page du <map> décrivant la carte d'image à utiliser. L'URL locale commence par # suivi de l'ID de l'élément <map>, par exemple #ma-carte. Le <map> contient à son tour des <area> pour les zones cliquables.

HTMLImageElement.width

Un entier qui reflète l'attribut HTML width, indiquant la largeur affichée de l'image en pixels CSS.

HTMLImageElement.x Lecture seule

Un entier indiquant le décalage horizontal du bord gauche de la boîte de mise en page CSS de l'image par rapport à l'origine du bloc contenant <html>.

HTMLImageElement.y Lecture seule

Un entier indiquant le décalage vertical du bord supérieur de la boîte de mise en page CSS de l'image par rapport à l'origine du bloc contenant <html>.

Propriétés obsolètes

HTMLImageElement.align

Une chaîne de caractères indiquant l'alignement de l'image par rapport au contexte environnant. Les valeurs possibles sont "left", "right", "justify" et "center". Obsolète : utilisez plutôt le CSS (par exemple text-align, qui fonctionne aussi pour les images) pour définir l'alignement.

HTMLImageElement.border

Une chaîne de caractères définissant la largeur de la bordure entourant l'image. Obsolète : utilisez la propriété CSS border à la place.

HTMLImageElement.hspace

Un entier indiquant l'espace (en pixels) à laisser vide à gauche et à droite de l'image.

HTMLImageElement.longDesc

Une chaîne de caractères définissant l'URL où trouver une description longue du contenu de l'image. Cela servait à transformer l'image en lien automatiquement. En HTML moderne, placez plutôt un <img> dans un élément <a> définissant le lien.

HTMLImageElement.name

Une chaîne de caractères représentant le nom de l'élément.

HTMLImageElement.vspace

Un entier indiquant l'espace vide (en pixels) à laisser au-dessus et en dessous de l'image.

Méthodes d'instance

Hérite des méthodes de son parent, HTMLElement.

HTMLImageElement.decode()

Retourne une promesse (Promise) qui se résout lorsque l'image est décodée et qu'il est sûr de l'ajouter au DOM. Cela évite que le rendu de l'image ne bloque la prochaine frame si une image non décodée était ajoutée au DOM.

Erreurs

Si une erreur se produit lors du chargement ou du rendu de l'image, et qu'un gestionnaire d'évènement onerror a été configuré pour l'évènement error, ce gestionnaire est appelé. Cela peut arriver dans plusieurs situations :

L'attribut src est vide ou null.
L'URL src indiquée est la même que celle de la page courante.
L'image indiquée est corrompue et ne peut pas être chargée.
Les métadonnées de l'image sont corrompues de telle sorte qu'il est impossible d'en récupérer les dimensions, et aucune dimension n'a été définie dans les attributs de l'élément <img>.
L'image indiquée est dans un format non pris en charge par l'agent utilisateur.

Exemple

Création et insertion d'un élément d'image

js
const img1 = new Image(); // Constructeur Image
img1.src = "image1.png";
img1.alt = "texte alternatif";
document.body.appendChild(img1);

const img2 = document.createElement("img"); // Utilise le DOM HTMLImageElement
img2.src = "image2.jpg";
img2.alt = "autre texte alternatif";
document.body.appendChild(img2);

// Utiliser la première image du document
alert(document.images[0].src);

Obtenir la largeur et la hauteur

L'exemple suivant montre l'utilisation des propriétés height et width avec des images de dimensions variées :

html
<p>
  Image 1&nbsp;: sans height, width ou style
  <img id="image1" src="https://www.mozilla.org/images/mozilla-banner.gif" />
</p>

<p>
  Image 2&nbsp;: height="50", width="500", sans style
  <img
    id="image2"
    src="https://www.mozilla.org/images/mozilla-banner.gif"
    height="50"
    width="500" />
</p>

<p>
  Image 3&nbsp;: sans height, width, mais style="height: 50px; width: 500px;"
  <img
    id="image3"
    src="https://www.mozilla.org/images/mozilla-banner.gif"
    style="height: 50px; width: 500px;" />
</p>

<div id="output"></div>

js
const arrImages = [
  document.getElementById("image1"),
  document.getElementById("image2"),
  document.getElementById("image3"),
];

const objOutput = document.getElementById("output");
let strHtml = "<ul>";

for (let i = 0; i < arrImages.length; i++) {
  const img = arrImages[i];
  strHtml += `<li>image${i + 1}: height=${img.height}, width=${img.width}, style.height=${img.style.height}, style.width=${img.style.width}</li>`;
}

strHtml += "</ul>";

objOutput.innerHTML = strHtml;

L'élément HTML implémentant cette interface : <img>

Aider à améliorer MDN

Cette page vous a-t-elle été utile ?

Oui Non

Apprendre à contribuer

Cette page a été modifiée le 13 mai 2026 par les contributeur·ice·s du MDN.

Voir cette page sur GitHub • Signaler un problème avec ce contenu

API HTML DOM
HTMLImageElement
Constructeur
1. Image()
Propriétés d'instance
Méthodes d'instance
1. decode()
Héritage
Pages liées à HTML DOM
Guides
1. Utiliser les microtâches en JavaScript avec queueMicrotask()
2. Aller plus loin : Les microtâches et l'environnement d'exécution JavaScript