new Image() — Methode · JavaScript-Referenz

Signatur

new Image(width, height)

Beschreibung

Der Konstruktor new Image() erzeugt ein neues HTMLImageElement, das noch nicht im Dokument hängt. Das Ergebnis ist dasselbe wie bei document.createElement('img'). Optional kannst du gleich Breite und Höhe mitgeben. Sie werden als HTML-Attribute width und height gesetzt.

Typische Einsatzfälle sind das Vorladen von Bildern (Preloading), das Laden von Bildern zum Zeichnen in ein <canvas>, das Auslesen der natürlichen Bildmaße über naturalWidth/naturalHeight und einfache Tracking-Pixel. Sobald du src setzt, beginnt der Browser mit dem Laden, auch wenn das Element nie ins DOM eingefügt wird.

Ob das Laden fertig ist, erfährst du über die Events load und error oder mit der Promise-basierten Methode decode(). Diese löst erst auf, wenn das Bild dekodiert ist und ohne Ruckeln angezeigt werden kann.

Parameter

Name	Typ	Default	Beschreibung
$width	number		Breite des Bildes in CSS-Pixeln. Wird als Attribut `width` gesetzt.
$height	number		Höhe des Bildes in CSS-Pixeln. Wird als Attribut `height` gesetzt.

Rückgabewert

Typ

HTMLImageElement

Beschreibung

Ein neues, noch nicht ins Dokument eingefügtes <img>-Element.

Beispiele

Bild erzeugen und ins DOM einfügen

const img = new Image(200, 120);
img.src = '/bilder/logo.png';
img.alt = 'Firmenlogo';
document.body.append(img);

console.log(img.outerHTML);

Bild als Promise laden (Preloading)

const loadImage = (url) => new Promise((resolve, reject) => {
  const img = new Image();
  img.onload = () => resolve(img);
  img.onerror = () => reject(new Error(`Bild konnte nicht geladen werden: ${url}`));
  img.src = url; // src erst NACH den Handlern setzen
});

const main = async () => {
  try {
    const img = await loadImage('/bilder/foto.jpg');
    console.log(`Geladen: ${img.naturalWidth}×${img.naturalHeight}`);
  } catch (err) {
    console.error(err.message);
  }
};
main();

Geladen: 1920×1080

Bild mit decode() in ein Canvas zeichnen

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

const drawImage = async (url) => {
  const img = new Image();
  img.crossOrigin = 'anonymous'; // nötig, damit das Canvas nicht "tainted" wird
  img.src = url;
  await img.decode();
  canvas.width = img.naturalWidth;
  canvas.height = img.naturalHeight;
  ctx.drawImage(img, 0, 0);
  console.log('Gezeichnet');
};

drawImage('https://cdn.example.com/karte.png');

Gezeichnet

Mehrere Bilder parallel vorladen

const urls = ['/img/a.jpg', '/img/b.jpg', '/img/c.jpg'];

const preloadAll = (list) => Promise.all(
  list.map((url) => {
    const img = new Image();
    img.src = url;
    return img.decode().then(() => img);
  })
);

preloadAll(urls).then((images) => console.log(`${images.length} Bilder bereit`));

3 Bilder bereit

// Wichtig · Fallstricke

Reihenfolge: Hänge die Handler onload/onerror an, bevor du src setzt. Kommt das Bild aus dem Cache, kann das Event sonst schon gefeuert haben, bevor der Handler hängt.
Kein Laden ohne src: Ohne src (oder srcset) passiert nichts. decode() wird dann mit einer EncodingError-DOMException abgelehnt, ebenso bei defekten Bilddaten.
Canvas und CORS: Zeichnest du Bilder von fremden Origins ohne crossOrigin = 'anonymous' und passenden Access-Control-Allow-Origin-Header ins Canvas, wird das Canvas „tainted“. Dann werfen getImageData() und toDataURL() einen SecurityError.
Maße: width/height aus dem Konstruktor legen nur die Darstellungsgröße fest. Die echten Pixelmaße liefern naturalWidth/naturalHeight, und zwar erst nach dem Laden.
Sicherheit: Setze nicht ungeprüft Adressen aus Benutzereingaben als src. Sonst können unerwünschte Anfragen ausgelöst werden, etwa Tracking oder Anfragen an interne Adressen. Die CSP-Direktive img-src schränkt ein, von welchen Quellen Bilder geladen werden dürfen.
Nur im Browser: Der Konstruktor steht nur im Fenster-Kontext zur Verfügung, also nicht in Web Workern und nicht in Node.js. Im Worker verwendest du fetch() zusammen mit createImageBitmap().

Siehe auch

new CSSMathSum() new Range() new File() new ImageData() new Audio()