HTMLImageElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLImageElement extends HTMLElement

Beschreibung

Das Interface HTMLImageElement steht für jedes <img>-Element im Dokument. Es erbt von HTMLElement und ergänzt bildspezifische Eigenschaften wie src, srcset, sizes, alt, width/height, naturalWidth/naturalHeight, complete, currentSrc, loading, decoding, crossOrigin, referrerPolicy und fetchPriority.

Instanzen entstehen entweder durch das Parsen von HTML, über document.createElement("img") oder über den Konstruktor new Image(width, height). Ein Bild wird bereits geladen, sobald src gesetzt ist – auch wenn das Element noch nicht im DOM hängt. Das macht es zum klassischen Werkzeug zum Vorladen (Preloading) von Bildern.

Wichtige Einsatzfälle sind: Bilder dynamisch nachladen, auf das Ende des Ladevorgangs warten (Ereignisse load und error oder die Promise-basierte Methode decode()), die tatsächlichen Pixelmaße auslesen (naturalWidth) sowie Bilder als Quelle für <canvas> oder createImageBitmap() verwenden.

Beachte: width und height geben die dargestellte (bzw. per Attribut gesetzte) Größe zurück, naturalWidth/naturalHeight dagegen die intrinsische Größe der Bilddatei. Beide sind erst nach dem Laden verlässlich.

Parameter

Name	Typ	Default	Beschreibung
$width	number		Nur für den Konstruktor `new Image(width, height)`: setzt das Attribut `width` in CSS-Pixeln.
$height	number		Nur für den Konstruktor `new Image(width, height)`: setzt das Attribut `height` in CSS-Pixeln.

Rückgabewert

Typ

HTMLImageElement

Beschreibung

new Image() bzw. document.createElement("img") liefern ein neues, noch nicht eingehängtes HTMLImageElement.

Beispiele

Bild erzeugen und einfügen

const img = new Image(320, 200);
img.src = "/bilder/logo.png";
img.alt = "Firmenlogo";
img.loading = "lazy";
img.decoding = "async";

document.querySelector("#header").append(img);
console.log(img instanceof HTMLImageElement, img.width);

true 320

Bild vorladen und auf decode() warten

const ladeBild = async (url) => {
  const img = new Image();
  img.src = url;
  await img.decode(); // wirft bei Ladefehler
  return img;
};

try {
  const img = await ladeBild("/bilder/foto.jpg");
  console.log(`Intrinsische Größe: ${img.naturalWidth}×${img.naturalHeight}`);
  document.body.append(img);
} catch (err) {
  console.error("Bild konnte nicht geladen werden:", err.message);
}

Intrinsische Größe: 1920×1080

load/error-Ereignisse und bereits gecachte Bilder

const img = document.querySelector("img.avatar");

const fertig = () => console.log("Geladen:", img.currentSrc);
const fehler = () => { img.src = "/bilder/platzhalter.png"; };

if (img.complete && img.naturalWidth > 0) {
  fertig(); // bereits aus dem Cache geladen
} else {
  img.addEventListener("load", fertig, { once: true });
  img.addEventListener("error", fehler, { once: true });
}

Geladen: https://example.com/bilder/avatar@2x.png

Responsives Bild mit srcset und Canvas-Verwendung

const img = new Image();
img.crossOrigin = "anonymous"; // nötig, um das Canvas nicht zu "verschmutzen"
img.srcset = "/bilder/klein.jpg 480w, /bilder/gross.jpg 1200w";
img.sizes = "(max-width: 600px) 480px, 1200px";
img.src = "/bilder/gross.jpg"; // Fallback

await img.decode();
const canvas = document.createElement("canvas");
canvas.width = img.naturalWidth;
canvas.height = img.naturalHeight;
canvas.getContext("2d").drawImage(img, 0, 0);
console.log(canvas.toDataURL("image/webp").slice(0, 22));

data:image/webp;base64

// Wichtig · Fallstricke

Reihenfolge: Event-Listener für load/error vor dem Setzen von src registrieren – sonst kann das Ereignis bei gecachten Bildern verpasst werden. Alternativ complete prüfen oder decode() nutzen.
complete ist auch bei fehlgeschlagenem Laden true; zusätzlich naturalWidth > 0 prüfen.
CORS: Cross-Origin-Bilder ohne crossOrigin und passende Access-Control-Allow-Origin-Header machen ein Canvas „tainted“ – toDataURL() und getImageData() werfen dann einen SecurityError.
Sicherheit: URLs aus Nutzereingaben nicht ungeprüft in src setzen (Tracking-Pixel, Datenabfluss); CSP-Direktive img-src beachten. Werte nie per innerHTML zusammenbauen (XSS über onerror-Attribute).
alt immer setzen (Barrierefreiheit); für rein dekorative Bilder alt = \"\".
Kompatibilität: Grundfunktionen in allen Browsern; decode(), loading=\"lazy\" und fetchPriority sind neuer – in sehr alten Browsern fehlen sie (Safari unterstützt loading=\"lazy\" erst ab 15.4).
Für <picture>-Konstrukte liefert currentSrc die tatsächlich gewählte Quelle, nicht src.

Siehe auch

HTMLBaseElement HTMLIFrameElement HTMLMapElement HTMLTimeElement HTMLAreaElement