Document: DOMContentLoaded — Ereignis · JavaScript-Referenz

Signatur

document.addEventListener("DOMContentLoaded", handler)

Beschreibung

Das Ereignis DOMContentLoaded wird auf dem Document ausgelöst, sobald der Browser das HTML vollständig eingelesen und den DOM-Baum aufgebaut hat. Vorher werden noch alle verzögerten Skripte ausgeführt, also <script defer src="…"> und <script type="module">. Auf Stylesheets, Bilder, iframes und asynchrone Skripte (async) wartet der Browser dagegen nicht. Wenn die ganze Seite samt aller Ressourcen geladen ist, feuert das Ereignis load auf window.

Typischerweise startet man mit DOMContentLoaded Initialisierungscode, der auf DOM-Elemente zugreift: Event-Listener registrieren, Widgets starten, Formulare vorbereiten. Das Ereignis kommt meist deutlich früher als load. Die Seite reagiert dadurch schneller.

Es gibt keine Eigenschaft document.onDOMContentLoaded, die zuverlässig funktioniert. Deshalb muss man den Listener mit addEventListener registrieren. Das Ereignis steigt bis window auf (Bubbling), man kann also auch an window lauschen. Der Handler erhält ein normales Event-Objekt ohne besondere Zusatzdaten.

Man braucht dieses Ereignis in modernem Code seltener, als oft angenommen: Skripte mit defer oder type="module" laufen ohnehin erst, wenn der DOM fertig geparst ist.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"DOMContentLoaded"`. Groß- und Kleinschreibung muss genau stimmen.
$handler Pflicht	(event: Event) => void		Callback, der einmal aufgerufen wird, sobald der DOM bereit ist.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `{ once: true }` oder ein `AbortSignal` unter `signal`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event-Objekt; es ist nicht abbrechbar und steigt bis window auf.

Beispiele

Initialisierung nach dem Parsen

document.addEventListener("DOMContentLoaded", () => {
  const button = document.querySelector("#absenden");
  button.addEventListener("click", () => console.log("Formular abgeschickt"));
  console.log("DOM bereit, Listener registriert");
});

DOM bereit, Listener registriert

Robust: auch funktionieren, wenn der DOM schon geladen ist

const init = () => {
  console.log("App gestartet, readyState:", document.readyState);
};

if (document.readyState === "loading") {
  // Dokument wird noch geparst
  document.addEventListener("DOMContentLoaded", init, { once: true });
} else {
  // DOMContentLoaded ist bereits vorbei
  init();
}

App gestartet, readyState: interactive

Listener wieder entfernen mit removeEventListener

const onReady = () => console.log("Nur beim ersten Laden ausgeführt");

document.addEventListener("DOMContentLoaded", onReady);

// Falls die Initialisierung doch nicht mehr gewünscht ist:
const abbrechen = true;
if (abbrechen) {
  document.removeEventListener("DOMContentLoaded", onReady);
}

Zeitpunkt von DOMContentLoaded und load vergleichen

const start = performance.now();

document.addEventListener("DOMContentLoaded", () => {
  console.log(`DOMContentLoaded nach ${Math.round(performance.now() - start)} ms`);
});

window.addEventListener("load", () => {
  console.log(`load (inkl. Bilder) nach ${Math.round(performance.now() - start)} ms`);
});

DOMContentLoaded nach 12 ms load (inkl. Bilder) nach 480 ms

// Wichtig · Fallstricke

Zu spät registriert: Registriert man den Listener erst nach dem Ereignis, z. B. in einem async-Skript oder einem nachgeladenen Skript, wird er nie aufgerufen. Deshalb vorher document.readyState prüfen.
Kein on-Property: document.onDOMContentLoaded = … ist nicht standardisiert und funktioniert nicht zuverlässig. Immer addEventListener verwenden.
Stylesheets: Das Ereignis wartet nicht auf CSS. Ein synchrones Skript, das hinter einem <link rel="stylesheet"> steht, wartet aber auf dieses Stylesheet, und damit verzögert sich auch DOMContentLoaded.
Blockierende Skripte: Synchrone <script>-Tags ohne defer halten den Parser an und verzögern das Ereignis. Mit defer oder Modulen lädt die Seite schneller.
Auf Bilder warten: Wer Bildgrößen oder das fertige Layout braucht, sollte window-load verwenden oder auf img.decode() warten.
Kompatibilität: Wird von allen modernen Browsern unterstützt, im Internet Explorer ab Version 9.

Siehe auch

Document.readyState EventTarget.addEventListener() EventTarget.removeEventListener() Element: MozMousePixelScroll Document: pointerlockerror