FontFace — Schnittstelle · JavaScript-Referenz

Signatur

interface FontFace

Beschreibung

FontFace ist das JavaScript-Gegenstück zur CSS-Regel @font-face. Ein FontFace-Objekt beschreibt eine Schrift: ihre Quelle (URL oder Binärdaten) und Deskriptoren wie weight, style, unicodeRange oder display. Anders als bei reinem CSS bestimmst du selbst, wann die Schrift geladen wird, und erfährst über ein Promise, ob das Laden geklappt hat.

Ein neues Objekt legst du mit new FontFace(family, source, descriptors) an. Mit load() startest du den Download. Die Eigenschaft loaded liefert ein Promise, das mit dem fertigen FontFace erfüllt wird. status zeigt den aktuellen Stand an: "unloaded", "loading", "loaded" oder "error". Nutzbar wird die Schrift erst, wenn du sie mit document.fonts.add(fontFace) in ein FontFaceSet einträgst. In Workern verwendest du dafür self.fonts.

Typische Einsatzfälle:

Schriften bedarfsgesteuert nachladen, z. B. erst wenn ein bestimmtes Modul geöffnet wird.
Ein Aufblitzen ungestylten oder unsichtbaren Texts (FOUT/FOIT) gezielt vermeiden.
Schriften aus einem ArrayBuffer einbinden, etwa aus IndexedDB oder aus einer fetch-Antwort.
Text in ein Canvas zeichnen, was nur mit einer bereits geladenen Schrift zuverlässig funktioniert.

Die Deskriptoren sind nach dem Anlegen als Lese- und Schreib-Eigenschaften verfügbar: family, style, weight, stretch, unicodeRange, featureSettings, variationSettings, display und ascentOverride, descentOverride, lineGapOverride. Die Deskriptor-Werte folgen der Syntax der entsprechenden @font-face-Deskriptoren.

Parameter

Name	Typ	Default	Beschreibung
$family Pflicht	string		Name der Schriftfamilie, wie er später in CSS verwendet wird, z. B. `font-family: 'Inter'`. Entspricht dem Deskriptor `font-family`.
$source Pflicht	string \| ArrayBuffer \| ArrayBufferView		Entweder ein String in der Syntax des `src`-Deskriptors, z. B. `"url(/fonts/inter.woff2) format('woff2')"`, oder die Binärdaten der Schrift. Wichtig: Eine URL muss in `url(...)` eingeschlossen sein.
$descriptors	object	{}	Optionale Deskriptoren: `style`, `weight`, `stretch`, `unicodeRange`, `featureSettings`, `variationSettings`, `display`, `ascentOverride`, `descentOverride`, `lineGapOverride`. Alle werden als Strings angegeben, z. B. `{ weight: '700', style: 'italic' }`.

Rückgabewert

Typ

FontFace

Beschreibung

Ein neues FontFace-Objekt. Bei einer URL-Quelle ist sein status zunächst "unloaded". Bei Binärdaten beginnt das Einlesen sofort.

Beispiele

Webfont per URL laden und registrieren

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

console.log(inter.status); // Ladestatus vor dem Start

try {
  const loaded = await inter.load();
  document.fonts.add(loaded);
  document.body.style.fontFamily = 'Inter, sans-serif';
  console.log(loaded.status);
} catch (err) {
  console.error('Schrift konnte nicht geladen werden:', err);
}

unloaded loaded

Schrift aus einem ArrayBuffer (fetch) einbinden

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

const roboto = new FontFace('Roboto', buffer, { weight: '400' });
await roboto.loaded; // wird erfüllt, sobald die Binärdaten eingelesen sind
document.fonts.add(roboto);

console.log(document.fonts.check('16px Roboto'));

true

Canvas-Text erst nach dem Laden der Schrift zeichnen

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

const display = new FontFace('Lobster', "url(/fonts/Lobster.woff2)");
document.fonts.add(display);

await display.load();
ctx.font = '48px Lobster';
ctx.fillText('Hallo Welt', 20, 60);

Deskriptoren nachträglich auslesen und ändern

const face = new FontFace('Mono', "url(/fonts/mono.woff2)", {
  unicodeRange: 'U+0000-00FF'
});

console.log(face.family, face.weight, face.unicodeRange);
face.weight = '300';
console.log(face.weight);

Mono normal U+0-FF 300

// Wichtig · Fallstricke

Hinzufügen nicht vergessen: Eine geladene FontFace wird erst nach document.fonts.add() vom CSS verwendet. Ohne diesen Schritt wird sie nirgends angewendet.
Quell-Syntax: Ein bloßer Pfad wie '/fonts/a.woff2' als source ist ungültig. Dann wird status zu \"error\" und load() schlägt mit einem SyntaxError fehl. Richtig ist 'url(/fonts/a.woff2)'.
Ungültige Deskriptoren führen ebenfalls zu einem abgelehnten loaded-Promise, z. B. weight: 'fett'. Den Aufruf daher in try/catch einbetten.
CORS: Schriften von fremden Ursprüngen brauchen den Header Access-Control-Allow-Origin, sonst scheitert das Laden. Auch die Content Security Policy muss die Quelle erlauben (font-src).
Serialisierung: Numerische Werte werden als Strings normalisiert. Die Ausgabe kann sich von der Eingabe unterscheiden, z. B. wird U+0000-00FF zu U+0-FF.
Kompatibilität: In allen aktuellen Browsern verfügbar, in Workern über self.fonts. Die Override-Deskriptoren (ascentOverride usw.) fehlen in Safari teilweise. Im Internet Explorer gibt es die API nicht.

Siehe auch

Document.fonts FontData FontFaceSet Fence DataCue