FontFaceSet: loading — Ereignis · JavaScript-Referenz

Signatur

document.fonts.addEventListener("loading", handler)

Beschreibung

Das Ereignis loading gehört zur CSS Font Loading API. Es wird am FontFaceSet des Dokuments (document.fonts) bzw. eines Workers (self.fonts) ausgelöst, sobald eine oder mehrere Schriften zu laden beginnen. Dabei wechselt FontFaceSet.status von "loaded" auf "loading".

Das Ereignis ist ein FontFaceSetLoadEvent. Seine Eigenschaft fontfaces enthält ein Array der FontFace-Objekte, die gerade laden. Registrieren kannst du den Handler per addEventListener("loading", …) oder über die Eigenschaft document.fonts.onloading.

Typische Anwendungen sind Ladeanzeigen, Messungen der Font-Performance oder ein Umschalten von CSS-Klassen, damit kein unschönes Springen der Schrift (FOUT/FOIT) entsteht. Das passende Gegenstück ist loadingdone, das feuert, wenn alle anstehenden Ladevorgänge fertig sind. Bei Fehlern wird loadingerror ausgelöst.

Beachte: Das Ereignis feuert nur, wenn tatsächlich ein Ladevorgang beginnt. Schriften, die schon im Cache liegen oder vor der Registrierung des Handlers geladen wurden, lösen es unter Umständen nicht (mehr) aus.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"loading"`.
$handler Pflicht	(event: FontFaceSetLoadEvent) => void		Callback-Funktion. Sie erhält ein `FontFaceSetLoadEvent` mit der Eigenschaft `fontfaces` (Array von `FontFace`).
$options	boolean\|AddEventListenerOptions	false	Optionen wie `{ once: true }` oder `{ signal }` zum späteren Entfernen.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein FontFaceSetLoadEvent.

Beispiele

Ladebeginn mit addEventListener protokollieren

document.fonts.addEventListener("loading", (event) => {
  const namen = event.fontfaces.map((f) => `${f.family} ${f.weight}`);
  console.log(`Lade ${namen.length} Schrift(en):`, namen.join(", "));
  console.log("Status:", document.fonts.status);
});

// Ladevorgang explizit anstoßen
const font = new FontFace("Inter", "url(/fonts/Inter-Bold.woff2)", { weight: "700" });
document.fonts.add(font);
font.load();

Lade 1 Schrift(en): Inter 700 Status: loading

Ladeanzeige per onloading und onloadingdone

const root = document.documentElement;

document.fonts.onloading = () => {
  root.classList.add("fonts-loading");
};

document.fonts.onloadingdone = (event) => {
  root.classList.remove("fonts-loading");
  root.classList.add("fonts-ready");
  console.log(`${event.fontfaces.length} Schrift(en) fertig geladen`);
};

2 Schrift(en) fertig geladen

Ladedauer messen und Listener wieder entfernen

let start = 0;

const onLoading = () => {
  start = performance.now();
};

const onDone = () => {
  console.log(`Fonts geladen in ${Math.round(performance.now() - start)} ms`);
  // Nur einmal messen: Listener entfernen
  document.fonts.removeEventListener("loading", onLoading);
  document.fonts.removeEventListener("loadingdone", onDone);
};

document.fonts.addEventListener("loading", onLoading);
document.fonts.addEventListener("loadingdone", onDone);

Fonts geladen in 142 ms

// Wichtig · Fallstricke

Zeitpunkt der Registrierung: Web-Fonts aus CSS können schon zu laden beginnen, bevor dein Skript läuft. Registriere den Handler deshalb früh oder prüfe zusätzlich document.fonts.status. Wenn du nur warten willst, bis alles geladen ist, ist await document.fonts.ready robuster.
Lazy Loading: Browser laden @font-face-Schriften erst, wenn sie tatsächlich verwendet werden. Ohne Text, der die Schrift nutzt, feuert loading gar nicht.
Mehrfaches Auslösen: Das Ereignis kann mehrmals feuern, z. B. wenn später dynamisch neue Schriften nachgeladen werden.
Kompatibilität: Wird in Chrome, Edge, Firefox und Safari unterstützt (Safari seit Version 10, bei den Events teils später). In Web Workern steht die API über self.fonts nicht in allen Browsern zur Verfügung. Vorher mit \"fonts\" in document prüfen.

Siehe auch

FontFaceSet FontFaceSet: loadingdone FontFaceSet: loadingerror FontFaceSet.ready FontFaceSet.status FontFaceSetLoadEvent FontFace Document.fonts