Signatur
Beschreibung
Die Eigenschaft variationSettings eines FontFace-Objekts enthält die Variationsachsen einer variablen Schrift (Variable Font) als String. Sie entspricht dem Deskriptor font-variation-settings innerhalb einer @font-face-Regel. Der Standardwert ist "normal".
Der Wert ist eine kommagetrennte Liste von Paaren aus Achsen-Tag und Zahl, z. B. '"wght" 650, "wdth" 85'. Jedes Achsen-Tag besteht aus genau vier ASCII-Zeichen in Anführungszeichen. Dabei wird Groß- und Kleinschreibung unterschieden: Registrierte Achsen wie wght, wdth, slnt, ital und opsz schreibt man klein. Eigene Achsen des Schriftherstellers (z. B. GRAD) schreibt man groß.
Den Wert kannst du auf zwei Wegen festlegen: beim Erzeugen über das Deskriptor-Objekt des Konstruktors (new FontFace(family, source, { variationSettings })) oder nachträglich durch Zuweisung. Sinnvoll ist das, wenn du Schriften dynamisch per FontFaceSet (document.fonts) lädst und eigene Achsen voreinstellen willst, für die es keinen CSS-Deskriptor auf höherer Ebene gibt.
Für registrierte Achsen solltest du lieber die höheren Eigenschaften weight, stretch und style verwenden. variationSettings ist ein niedrigstufiges Werkzeug und überschreibt diese Werte, ohne den Browser zu informieren. Das kann zum Beispiel die Auswahl der passenden Schrift oder synthetischen Fettdruck stören.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | string | "normal" | Beim Setzen: "normal" oder eine kommagetrennte Liste aus "tag" zahl, z. B. '"wght" 700, "GRAD" 50'. Bei ungültiger Syntax wird ein SyntaxError (DOMException) ausgelöst. |
Rückgabewert
"normal". Der Browser kann den String normalisieren, z. B. Leerzeichen oder die Schreibweise der Zahlen anpassen.Beispiele
Variable Schrift mit Variationen laden
const font = new FontFace(
'RobotoFlex',
'url(/fonts/RobotoFlex.woff2) format("woff2")',
{ variationSettings: '"wdth" 110, "GRAD" 50' }
);
console.log(font.variationSettings);
const loaded = await font.load();
document.fonts.add(loaded);
document.body.style.fontFamily = 'RobotoFlex, sans-serif';Standardwert lesen und nachträglich ändern
const font = new FontFace('Inter', 'url(/fonts/Inter.var.woff2)');
console.log(font.variationSettings); // Standardwert
font.variationSettings = '"opsz" 32';
console.log(font.variationSettings);Ungültige Werte abfangen
const font = new FontFace('Demo', 'url(/fonts/demo.woff2)');
const setVariation = (face, value) => {
try {
face.variationSettings = value;
return true;
} catch (err) {
console.warn(`Ungültiger Wert: ${err.name}`);
return false;
}
};
setVariation(font, '"wght" 600'); // gültig
setVariation(font, 'wght 600'); // Tag ohne Anführungszeichen
setVariation(font, '"wg" 600'); // Tag hat nicht 4 ZeichenAlle geladenen Schriften mit Variationen auflisten
await document.fonts.ready;
const variableFaces = [...document.fonts]
.filter((face) => face.variationSettings !== 'normal')
.map((face) => ({ family: face.family, settings: face.variationSettings }));
console.table(variableFaces);// Wichtig · Fallstricke
- Browser-Unterstützung: Chromium-Browser und Safari unterstützen die Eigenschaft. Firefox stellt sie am
FontFace-Objekt nicht bereit. Prüfe die Unterstützung vorher, z. B. mit'variationSettings' in FontFace.prototype. - Groß- und Kleinschreibung: Achsen-Tags werden nach Groß-/Kleinschreibung unterschieden.
"WGHT"ist nicht die registrierte Gewichtsachse"wght". Achsen, die die Schrift nicht kennt, werden stillschweigend ignoriert. - Vorrang: Für Gewicht, Breite und Neigung besser
weight,stretchundstyleverwenden.variationSettingswird später angewendet, überschreibt diese Werte und macht die Auswahl der passenden Schrift unzuverlässig. - Nicht-variable Schriften: Die Einstellung hat keine sichtbare Wirkung, wenn die Schriftdatei keine Variationsachsen enthält.
- Werte außerhalb des Bereichs: Der Browser begrenzt sie auf den Bereich, den die Schrift unterstützt. Einen Fehler gibt es dabei nicht.
- Nachträgliche Änderung: Wenn du den Wert nach dem Hinzufügen zu
document.fontsänderst, wird bereits gerenderter Text je nach Browser nicht immer sofort neu dargestellt. Am zuverlässigsten ist es, den Wert vorload()zu setzen.