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 bnficier de prise en charge variables.

En savoir plus
Voir la compatibilit complte

L'interface HTMLImageElement reprsente un lment HTML <img>, fournissant les proprits et mthodes utilises pour manipuler les lments image.

EventTarget Node Element HTMLElement HTMLImageElement

Constructeur

Image(): Le constructeur Image() cre et retourne un nouvel objet HTMLImageElement reprsentant un lment HTML <img> qui n'est pas attach un arbre DOM. Il accepte des paramtres optionnels de largeur et de hauteur. Appel sans paramtre, new Image() est quivalent document.createElement('img').

Proprits d'instance

Hrite des proprits de son parent, HTMLElement.

HTMLImageElement.alt: Une chane de caractres qui reflte l'attribut HTML alt, indiquant le contenu de remplacement afficher si l'image n'a pas t charge.
HTMLImageElement.attributionSrc Contexte scuris: Permet d'obtenir ou de dfinir l'attribut attributionsrc sur un lment <img> de faon programmatique, refltant la valeur de cet attribut. attributionsrc indique que le navigateur doit envoyer un en-tte Attribution-Reporting-Eligible avec la requte d'image. Ct serveur, cela sert dclencher l'envoi d'un en-tte Attribution-Reporting-Register-Source ou Attribution-Reporting-Register-Trigger dans la rponse, afin d'enregistrer une source d'attribution ou un dclencheur d'attribution.
HTMLImageElement.complete Lecture seule: Retourne une valeur boolenne true si le navigateur a fini de rcuprer l'image, que ce soit avec succs ou non. Cela vaut aussi true si l'image n'a pas de valeur src indiquant une image charger.
HTMLImageElement.crossOrigin: Une chane de caractres indiquant le paramtrage CORS pour cet lment image. Voir les attributs de paramtrage du CORS pour plus de dtails. Peut valoir null si CORS n'est pas utilis.
HTMLImageElement.currentSrc Lecture seule: Retourne une chane de caractres reprsentant l'URL depuis laquelle l'image actuellement affiche a t charge. Cette valeur peut changer si l'image est modifie en fonction des conditions, par exemple avec des requtes mdia.
HTMLImageElement.decoding: Une chane de caractres optionnelle indiquant une prfrence sur la faon dont le navigateur doit dcoder l'image. Les valeurs possibles sont : sync (dcodage synchrone), async (dcodage asynchrone), ou auto (pas de prfrence, valeur par dfaut). Voir la page decoding pour plus de dtails.
HTMLImageElement.fetchPriority: Une chane de caractres optionnelle indiquant une prfrence sur la priorit de rcupration de l'image par rapport aux autres images. Les valeurs possibles sont : high (priorit haute), low (priorit basse), ou auto (pas de prfrence, valeur par dfaut).
HTMLImageElement.height: Un entier qui reflte l'attribut HTML height, indiquant la hauteur affiche de l'image en pixels CSS.
HTMLImageElement.isMap: Un boolen qui reflte l'attribut HTML ismap, indiquant que l'image fait partie d'une carte ct serveur. Diffrent d'une carte ct client, qui utilise un lment <img> et un <map> contenant des <area> pour les zones cliquables. L'image doit tre contenue dans un lment <a> ; voir la page ismap pour plus de dtails.
HTMLImageElement.loading: Une chane de caractres indiquant si le navigateur doit charger l'image immdiatement (eager) ou lorsqu'elle est ncessaire (lazy).
HTMLImageElement.naturalHeight Lecture seule: Retourne un entier reprsentant la hauteur intrinsque de l'image en pixels CSS, si disponible ; sinon, retourne 0. C'est la hauteur que l'image aurait si elle tait affiche sa taille naturelle.
HTMLImageElement.naturalWidth Lecture seule: Un entier reprsentant la largeur intrinsque de l'image en pixels CSS, si disponible ; sinon, retourne 0. C'est la largeur que l'image aurait si elle tait affiche sa taille naturelle.
HTMLImageElement.referrerPolicy: Une chane de caractres qui reflte l'attribut HTML referrerpolicy, indiquant l'agent utilisateur quelle politique de rfrent utiliser pour rcuprer l'image. Voir l'article pour les valeurs possibles.
HTMLImageElement.sizes: Une chane de caractres refltant l'attribut HTML sizes. Cette chane de caractres dfinit une liste de tailles conditionnelles spares par des virgules pour l'image ; c'est--dire, pour une taille de zone d'affichage donne, une taille d'image particulire est utilise. Voir la documentation de sizes pour le format de cette chane.
HTMLImageElement.src: Une chane de caractres qui reflte l'attribut HTML src, contenant l'URL complte de l'image (y compris la base). Vous pouvez charger une autre image en modifiant l'URL dans l'attribut src.
HTMLImageElement.srcset: Une chane de caractres refltant l'attribut HTML srcset. Cela dfinit une liste d'images candidates, spares par des virgules. Chaque image candidate est une URL suivie d'un espace, puis d'une chane indiquant la taille de l'image (largeur ou multiple de taille). Voir la page srcset pour le format dtaill.
HTMLImageElement.useMap: Une chane de caractres refltant l'attribut HTML usemap, contenant l'URL locale de la page du <map> dcrivant la carte d'image utiliser. L'URL locale commence par # suivi de l'ID de l'lment <map>, par exemple #ma-carte. Le <map> contient son tour des <area> pour les zones cliquables.
HTMLImageElement.width: Un entier qui reflte l'attribut HTML width, indiquant la largeur affiche de l'image en pixels CSS.
HTMLImageElement.x Lecture seule: Un entier indiquant le dcalage horizontal du bord gauche de la bote de mise en page CSS de l'image par rapport l'origine du bloc contenant <html>.
HTMLImageElement.y Lecture seule: Un entier indiquant le dcalage vertical du bord suprieur de la bote de mise en page CSS de l'image par rapport l'origine du bloc contenant <html>.

Proprits obsoltes

HTMLImageElement.align: Une chane de caractres indiquant l'alignement de l'image par rapport au contexte environnant. Les valeurs possibles sont "left", "right", "justify" et "center". Obsolte : utilisez plutt le CSS (par exemple text-align, qui fonctionne aussi pour les images) pour dfinir l'alignement.
HTMLImageElement.border: Une chane de caractres dfinissant la largeur de la bordure entourant l'image. Obsolte : utilisez la proprit CSS border la place.
HTMLImageElement.hspace: Un entier indiquant l'espace (en pixels) laisser vide gauche et droite de l'image.
HTMLImageElement.longDesc: Une chane de caractres dfinissant l'URL o trouver une description longue du contenu de l'image. Cela servait transformer l'image en lien automatiquement. En HTML moderne, placez plutt un <img> dans un lment <a> dfinissant le lien.
HTMLImageElement.name: Une chane de caractres reprsentant le nom de l'lment.
HTMLImageElement.vspace: Un entier indiquant l'espace vide (en pixels) laisser au-dessus et en dessous de l'image.

Mthodes d'instance

Hrite des mthodes de son parent, HTMLElement.

HTMLImageElement.decode(): Retourne une promesse (Promise) qui se rsout lorsque l'image est dcode et qu'il est sr de l'ajouter au DOM. Cela vite que le rendu de l'image ne bloque la prochaine frame si une image non dcode tait ajoute au DOM.

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

L'attribut src est vide ou null.
L'URL src indique est la mme que celle de la page courante.
L'image indique est corrompue et ne peut pas tre charge.
Les mtadonnes de l'image sont corrompues de telle sorte qu'il est impossible d'en rcuprer les dimensions, et aucune dimension n'a t dfinie dans les attributs de l'lment <img>.
L'image indique est dans un format non pris en charge par l'agent utilisateur.

Exemple

Cration et insertion d'un lment d'image

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 premire image du document
alert(document.images[0].src);

Obtenir la largeur et la hauteur

L'exemple suivant montre l'utilisation des proprits height et width avec des images de dimensions varies :

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 
  <img
    id="image3"
    src="https://www.mozilla.org/images/mozilla-banner.gif"
     />
</p>

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

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;

Spcifications

Spcification
HTML # htmlimageelement

Compatibilit des navigateurs

Voir aussi

L'lment HTML implmentant cette interface : <img>

Aider amliorer MDN

Cette page vous a-t-elle t utile ?

Oui Non

Apprendre contribuer

Cette page a t modifie le 13 mai 2026 par les contributeurices du MDN.

Voir cette page sur GitHub Signaler un problme avec ce contenu

API HTML DOM
HTMLImageElement
Constructeur
1. Image()
Proprits d'instance
Mthodes d'instance
1. decode()
Hritage
Pages lies HTML DOM
Guides
1. Utiliser les microtches en JavaScript avec queueMicrotask()
2. Aller plus loin : Les microtches et l'environnement d'excution JavaScript