HTMLImageElement.complete — Eigenschaft · JavaScript-Referenz

Signatur

get HTMLImageElement.complete

Beschreibung

Die Eigenschaft complete zeigt an, ob ein HTMLImageElement noch lädt oder schon fertig ist. Das ist vor allem wichtig, wenn Code erst ausgeführt wird, nachdem das Bild womöglich schon geladen ist, zum Beispiel bei Bildern aus dem Cache oder bei Skripten mit defer. Das load-Ereignis wurde dann schon ausgelöst, und ein neu registrierter Listener wird nie aufgerufen. Mit complete kann man das zuverlässig vorher prüfen.

Laut HTML-Spezifikation ist complete true, wenn mindestens einer dieser Fälle zutrifft:

Weder src noch srcset ist gesetzt.
srcset fehlt und src ist ein leerer String.
Das Bild ist vollständig heruntergeladen und dekodierbar (completely available).
Das Bild ist defekt (broken), etwa weil der Server 404 liefert oder das Format ungültig ist.

Deshalb bedeutet complete === true nicht, dass das Bild erfolgreich geladen wurde. Ob wirklich Bilddaten vorhanden sind, prüft man zusätzlich mit naturalWidth > 0. Das typische Vorgehen: Ist complete schon true, sofort auswerten. Sonst auf load bzw. error warten.

Beispiele

Bild-Status prüfen, bevor ein Listener registriert wird

const img = document.querySelector('#hero');

const onReady = () => {
  if (img.naturalWidth > 0) {
    console.log(`Geladen: ${img.naturalWidth}×${img.naturalHeight}`);
  } else {
    console.log('Bild ist defekt');
  }
};

if (img.complete) {
  // Schon fertig (z. B. aus dem Cache) – load-Ereignis wäre verpasst
  onReady();
} else {
  img.addEventListener('load', onReady, { once: true });
  img.addEventListener('error', onReady, { once: true });
}

Geladen: 1920×1080

Promise-Helfer: auf ein Bild warten

const waitForImage = (img) => new Promise((resolve, reject) => {
  if (img.complete) {
    return img.naturalWidth > 0
      ? resolve(img)
      : reject(new Error(`Bild defekt: ${img.src}`));
  }
  img.addEventListener('load', () => resolve(img), { once: true });
  img.addEventListener('error', () => reject(new Error(`Ladefehler: ${img.src}`)), { once: true });
});

const images = [...document.querySelectorAll('.gallery img')];
const results = await Promise.allSettled(images.map(waitForImage));
const ok = results.filter((r) => r.status === 'fulfilled').length;
console.log(`${ok} von ${images.length} Bildern geladen`);

5 von 6 Bildern geladen

Verhalten bei neu erzeugten Bildern

const img = new Image();
console.log(img.complete); // kein src → true

img.src = '/bilder/logo.png';
console.log(img.complete); // Laden läuft → meist false

img.addEventListener('load', () => {
  console.log(img.complete); // true
});

true false true

Defektes Bild erkennen

const img = new Image();
img.src = '/gibt-es-nicht.png';

img.addEventListener('error', () => {
  // complete ist true, obwohl nichts geladen wurde
  console.log(img.complete, img.naturalWidth);
});

true 0

// Wichtig · Fallstricke

Fehler zählen als „fertig“: Auch bei defekten Bildern (404, ungültiges Format, CORS-Fehler) ist complete true. Den Erfolg immer zusätzlich über naturalWidth > 0 oder das load-Ereignis prüfen.
Fehlende Quelle: Ein <img> ohne src/srcset oder mit leerem src ist sofort complete. Bei Platzhaltern kann das zu falschen Annahmen führen.
Lazy Loading: Bei loading="lazy" bleibt complete false, bis das Bild in die Nähe des sichtbaren Bereichs kommt und geladen ist. Wer auf alle Bilder wartet, blockiert dann womöglich sehr lange.
Race Condition: Erst den Listener registrieren und dann complete prüfen, oder wie in den Beispielen beides kombinieren. Sonst kann das load-Ereignis zwischen Prüfung und Registrierung verloren gehen.
src ändern: Nach einer Änderung von src wird complete in der Regel wieder false, bis die neue Quelle geladen ist. Liegt das Bild im Cache, kann es sofort wieder true sein.
Soll das Bild vor dem Einfügen ins DOM nicht nur geladen, sondern auch dekodiert sein, ist HTMLImageElement.decode() meist die bessere Wahl.
Kompatibilität: wird von allen gängigen Browsern unterstützt. Ältere Browser setzten complete in Randfällen (z. B. bei Fehlern) teils uneinheitlich.

Siehe auch

HTMLImageElement HTMLImageElement.naturalWidth HTMLImageElement.decode() HTMLImageElement.currentSrc HTMLImageElement.loading