new FontFace() — Methode · JavaScript-Referenz

Signatur

new FontFace(family, source, descriptors)

Beschreibung

Der Konstruktor FontFace() ist das JavaScript-Gegenstück zur CSS-Regel @font-face. Mit ihm lassen sich Webfonts zur Laufzeit definieren, gezielt laden und über document.fonts.add() für die Darstellung verfügbar machen. So bestimmen Sie selbst, wann eine Schrift heruntergeladen wird, und können auf Erfolg oder Fehler reagieren.

Als Quelle akzeptiert der Konstruktor entweder einen CSS-src-String (z. B. url("font.woff2") format("woff2")) oder Binärdaten als ArrayBuffer bzw. ArrayBufferView. Bei einer URL passiert zunächst nichts – der Download beginnt erst mit fontFace.load() oder wenn die Schrift nach dem Hinzufügen zu document.fonts tatsächlich benötigt wird. Bei Binärdaten wird die Schrift sofort geparst.

Typische Einsatzfälle sind: kritische Schriften vorab laden, um Layoutsprünge (FOUT/FOIT) zu vermeiden, Schriften dynamisch nachladen (z. B. in Editoren oder Canvas-Anwendungen), selbst erzeugte oder aus IndexedDB stammende Fontdaten einbinden sowie Schriften in Web Workern für OffscreenCanvas bereitstellen.

Parameter

Name	Typ	Default	Beschreibung
$family Pflicht	string		Name der Schriftfamilie, unter dem die Schrift später in CSS (`font-family`) oder in `ctx.font` angesprochen wird. Entspricht dem `font-family`-Deskriptor von `@font-face`.
$source Pflicht	string \| ArrayBuffer \| ArrayBufferView		Die Schriftquelle: entweder ein String in der Syntax des CSS-Deskriptors `src` (z. B. `url("/fonts/a.woff2") format("woff2")`, auch mehrere kommagetrennte Quellen oder `local()`) oder die Binärdaten einer Schriftdatei.
$descriptors	object	{}	Optionale Deskriptoren wie in `@font-face`: `style`, `weight`, `stretch`, `display`, `unicodeRange`, `featureSettings`, `variationSettings`, `ascentOverride`, `descentOverride`, `lineGapOverride`. Alle Werte sind Strings in CSS-Syntax, z. B. `{ weight: "700", style: "italic" }` oder für variable Fonts `{ weight: "100 900" }`.

Rückgabewert

Typ

FontFace

Beschreibung

Ein neues FontFace-Objekt. Bei URL-Quellen hat status anfangs den Wert "unloaded"; bei Binärdaten wird die Schrift sofort verarbeitet (status wird "loaded" oder "error").

Beispiele

Webfont per URL laden und im Dokument verwenden

const roboto = new FontFace(
  'Roboto',
  'url("/fonts/roboto-bold.woff2") format("woff2")',
  { weight: '700', style: 'normal', display: 'swap' }
);

try {
  const loaded = await roboto.load(); // startet den Download
  document.fonts.add(loaded);         // für CSS verfügbar machen
  document.body.style.fontFamily = 'Roboto, sans-serif';
  console.log(`${loaded.family} geladen:`, loaded.status);
} catch (err) {
  console.error('Schrift konnte nicht geladen werden:', err);
}

Roboto geladen: loaded

Schrift aus Binärdaten (ArrayBuffer) erstellen

const response = await fetch('/fonts/inter-var.woff2');
const buffer = await response.arrayBuffer();

// Variabler Font mit Gewichtsbereich
const inter = new FontFace('Inter', buffer, { weight: '100 900' });
console.log(inter.status); // Binärdaten werden sofort verarbeitet

await inter.loaded;
document.fonts.add(inter);
console.log(document.fonts.check('600 16px Inter'));

loading true

Schrift vor dem Zeichnen auf ein Canvas laden

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

const pixelFont = new FontFace('PixelFont', 'url("/fonts/pixel.woff2")');
document.fonts.add(await pixelFont.load());

// Erst jetzt zeichnen – sonst fällt Canvas auf die Standardschrift zurück
ctx.font = '32px PixelFont';
ctx.fillText('Level 1', 20, 50);

Mehrere Schnitte parallel laden

const faces = [
  new FontFace('Lato', 'url("/fonts/lato-400.woff2")', { weight: '400' }),
  new FontFace('Lato', 'url("/fonts/lato-700.woff2")', { weight: '700' }),
  new FontFace('Lato', 'url("/fonts/lato-400i.woff2")', { style: 'italic' })
];

const results = await Promise.allSettled(faces.map((f) => f.load()));
results.forEach((r, i) => {
  if (r.status === 'fulfilled') document.fonts.add(r.value);
  else console.warn('Fehlgeschlagen:', faces[i].weight, faces[i].style);
});
console.log('Geladene Lato-Schnitte:', [...document.fonts].filter((f) => f.family === 'Lato' && f.status === 'loaded').length);

Geladene Lato-Schnitte: 3

// Wichtig · Fallstricke

Erstellen heißt nicht laden: Bei einer URL als Quelle wird nichts heruntergeladen, bis load() aufgerufen wird oder die Schrift nach document.fonts.add() tatsächlich zum Rendern gebraucht wird. Canvas löst diesen Download nicht zuverlässig aus – vor dem Zeichnen immer await fontFace.load() verwenden.
Hinzufügen nicht vergessen: Eine geladene Schrift ist erst nach document.fonts.add(face) (bzw. self.fonts.add() im Worker) für CSS und Canvas nutzbar.
Syntax der Quelle: Der String muss gültige src-Syntax sein, also url(...) enthalten. Ein bloßer Pfad wie "/fonts/a.woff2" ist ungültig und führt zu status === "error". Ungültige Deskriptoren lösen einen SyntaxError aus (bzw. lassen das loaded-Promise ablehnen).
CORS: Schriften von fremden Origins werden nur geladen, wenn der Server einen passenden Access-Control-Allow-Origin-Header sendet. Auch eine strikte font-src-Direktive der Content Security Policy kann das Laden blockieren.
Deskriptoren sind Strings: weight: 700 funktioniert zwar durch Typumwandlung, korrekt ist aber weight: "700"; Bereiche für variable Fonts nur als String ("100 900").
Kompatibilität: Von allen aktuellen Browsern unterstützt (Chrome 35+, Firefox 41+, Safari 10+). Die Override-Deskriptoren (ascentOverride usw.) fehlen in Safari; in Workern ist self.fonts erst in neueren Versionen verfügbar.

Siehe auch

FontFace FontFace.prototype.load() FontFace.loaded FontFace.status FontFaceSet FontFaceSet.prototype.add() Document.fonts FontFaceSet.prototype.check()