HTMLElement: load — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("load", handler)

Beschreibung

Das load-Ereignis tritt an einem HTMLElement auf, sobald die zugehörige Ressource vollständig und erfolgreich geladen wurde. Typische Elemente sind <img>, <script>, <link rel="stylesheet">, <iframe>, <embed>, <object>, <style> und <track>. Schlägt das Laden fehl, wird stattdessen das error-Ereignis ausgelöst.

Man registriert den Handler entweder mit addEventListener("load", handler) oder über die Eigenschaft onload (bzw. das HTML-Attribut onload). Das Ereignis ist ein einfaches Event, ist nicht abbrechbar und blubbert nicht (bubbles: false). Eine Delegation über ein Elternelement funktioniert daher nur in der Capture-Phase ({ capture: true }).

Typische Einsatzfälle: dynamisch nachgeladene Skripte oder Stylesheets erst nach dem Laden verwenden, Bildabmessungen (naturalWidth/naturalHeight) auslesen, Lade-Platzhalter ausblenden oder mit einem <iframe> kommunizieren, sobald dessen Dokument bereit ist.

Nicht zu verwechseln mit Window: load, das erst feuert, wenn die gesamte Seite inklusive aller Unterressourcen geladen ist.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, hier `"load"`.
$handler Pflicht	(event: Event) => void		Callback, der ein `Event`-Objekt erhält; `event.target` ist das geladene Element.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `capture`, `signal`. `{ once: true }` ist für Ladeereignisse meist sinnvoll.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event-Objekt (nicht abbrechbar, blubbert nicht).

Beispiele

Bild laden und Abmessungen auslesen

const img = document.createElement('img');

// Handler VOR dem Setzen von src registrieren
img.addEventListener('load', () => {
  console.log(`Geladen: ${img.naturalWidth}×${img.naturalHeight}`);
  document.body.append(img);
}, { once: true });

img.addEventListener('error', () => {
  console.error('Bild konnte nicht geladen werden');
}, { once: true });

img.src = 'https://picsum.photos/400/300';

Geladen: 400×300

Skript dynamisch nachladen als Promise

const loadScript = (src) => new Promise((resolve, reject) => {
  const script = document.createElement('script');
  script.src = src;
  script.onload = () => resolve(script);
  script.onerror = () => reject(new Error(`Fehler beim Laden von ${src}`));
  document.head.append(script);
});

try {
  await loadScript('https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js');
  console.log(dayjs().format('YYYY-MM-DD'));
} catch (err) {
  console.error(err.message);
}

2024-05-17

Delegation per Capture und Entfernen des Listeners

const gallery = document.querySelector('#galerie');

// load blubbert nicht – daher capture: true
const onImageLoad = (event) => {
  if (event.target instanceof HTMLImageElement) {
    event.target.classList.add('geladen');
  }
};
gallery.addEventListener('load', onImageLoad, { capture: true });

// Später wieder entfernen (capture muss übereinstimmen)
setTimeout(() => {
  gallery.removeEventListener('load', onImageLoad, { capture: true });
  console.log('Listener entfernt');
}, 10000);

Listener entfernt

Bereits geladene Bilder berücksichtigen

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

const onReady = () => console.log('Hero-Bild bereit');

// Aus dem Cache geladene Bilder können schon fertig sein
if (img.complete && img.naturalWidth > 0) {
  onReady();
} else {
  img.addEventListener('load', onReady, { once: true });
}

// Alternative ohne Event: await img.decode();

Hero-Bild bereit

// Wichtig · Fallstricke

Wettlaufsituation: Den Listener immer vor dem Setzen von src/href registrieren. Bei bereits im HTML vorhandenen Bildern kann load schon ausgelöst worden sein – vorher img.complete prüfen oder img.decode() verwenden.
Kein Bubbling: load steigt nicht im DOM auf. Delegation nur mit { capture: true }; beim Entfernen muss capture identisch angegeben werden.
Fehlerfall: Bei 404, CORS-Fehlern oder ungültigen Daten feuert error, nicht load. Immer beide Ereignisse behandeln.
Lazy Loading: Bei loading="lazy" feuert load erst, wenn das Element in die Nähe des sichtbaren Bereichs kommt.
iframes: load wird bei jeder Navigation im iframe erneut ausgelöst; auch leere iframes (about:blank) können es auslösen. Zugriff auf contentDocument ist nur bei gleicher Herkunft möglich.
Sicherheit: Das HTML-Attribut onload="..." ist Inline-JavaScript und wird von einer strikten CSP (ohne 'unsafe-inline') blockiert. Außerdem ist <img src=x onload=...> bzw. onerror ein klassischer XSS-Vektor – nie unbereinigtes HTML per innerHTML einfügen.
Kompatibilität: In allen modernen Browsern unterstützt. <link rel="stylesheet">-load ist in allen aktuellen Engines verfügbar, war in sehr alten Browsern jedoch unzuverlässig.

Siehe auch

HTMLImageElement.complete HTMLImageElement.decode() EventTarget.addEventListener() EventTarget.removeEventListener() HTMLElement: drag