CSS.registerProperty() — Methode · JavaScript-Referenz

Signatur

CSS.registerProperty(propertyDefinition)

Beschreibung

CSS.registerProperty() ist eine statische Methode der CSS Properties and Values API (Teil von CSS Houdini). Normale Custom Properties wie --farbe sind für den Browser nur Zeichenketten ohne Typ. Nach der Registrierung kennt der Browser den Typ (z. B. <color>, <length>, <angle>), einen Startwert und weiß, ob die Eigenschaft vererbt wird.

Der größte praktische Nutzen: Registrierte Eigenschaften lassen sich animieren und per Transition überblenden, weil der Browser zwischen typisierten Werten interpolieren kann. So kann man zum Beispiel Farbverläufe animieren, was mit untypisierten Variablen nicht geht. Außerdem werden ungültige Werte verworfen und durch den Startwert ersetzt, statt die ganze Deklaration unbrauchbar zu machen.

Die Methode wird einmal pro Eigenschaft und Dokument aufgerufen, am besten früh beim Laden der Seite. Deklarativ geht dasselbe mit der CSS-At-Regel @property, die für statische Definitionen oft die bessere Wahl ist. CSS.registerProperty() eignet sich, wenn Eigenschaften dynamisch oder abhängig von einer Feature-Erkennung registriert werden sollen.

Parameter

Name	Typ	Default	Beschreibung
$propertyDefinition Pflicht	Object		Objekt, das die Eigenschaft beschreibt. Enthält die folgenden Felder.
$propertyDefinition.name Pflicht	string		Name der Eigenschaft. Muss mit `--` beginnen, z. B. `'--akzent'`.
$propertyDefinition.syntax	string	"*"	Syntax-Beschreibung des erlaubten Werts, z. B. `'<color>'`, `'<length> \| auto'` oder `'<number>+'`. `'*'` erlaubt jeden Wert.
$propertyDefinition.inherits Pflicht	boolean		Gibt an, ob der Wert an Kindelemente vererbt wird. In der Spezifikation ist das Feld Pflicht. Fehlt es, wirft Chrome einen `TypeError`.
$propertyDefinition.initialValue	string		Startwert der Eigenschaft. Pflicht, sobald `syntax` nicht `'*'` ist. Der Wert muss zur Syntax passen und berechnungsunabhängig sein, also z. B. `'10px'`, aber nicht `'2em'`.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Bei ungültigen Angaben wird eine Ausnahme geworfen.

Beispiele

Farbe registrieren und per Transition überblenden

// Einmalig beim Start registrieren
CSS.registerProperty({
  name: '--akzent',
  syntax: '<color>',
  inherits: false,
  initialValue: 'rebeccapurple'
});

// Passendes CSS dynamisch einfügen
const style = document.createElement('style');
style.textContent = `
  .button {
    background: linear-gradient(90deg, var(--akzent), white);
    transition: --akzent 0.4s ease;
  }
  .button:hover { --akzent: tomato; }
`;
document.head.append(style);

Winkel animieren (rotierender Farbverlauf)

CSS.registerProperty({
  name: '--winkel',
  syntax: '<angle>',
  inherits: false,
  initialValue: '0deg'
});

const box = document.querySelector('.box');
box.style.background = 'conic-gradient(from var(--winkel), red, blue, red)';

// Web Animations API: interpoliert dank Registrierung flüssig
box.animate(
  [{ '--winkel': '0deg' }, { '--winkel': '360deg' }],
  { duration: 3000, iterations: Infinity }
);

Feature-Erkennung und doppelte Registrierung abfangen

const registriere = (definition) => {
  if (!('registerProperty' in CSS)) {
    console.warn('Properties and Values API wird nicht unterstützt');
    return false;
  }
  try {
    CSS.registerProperty(definition);
    return true;
  } catch (err) {
    // InvalidModificationError bei doppelter Registrierung,
    // SyntaxError bei ungültigem Namen, ungültiger Syntax oder ungültigem Startwert
    console.error(err.name, err.message);
    return false;
  }
};

const def = { name: '--abstand', syntax: '<length>', inherits: true, initialValue: '8px' };
console.log(registriere(def));
console.log(registriere(def));

true InvalidModificationError ... false

Typprüfung: ungültiger Wert fällt auf den Startwert zurück

CSS.registerProperty({
  name: '--groesse',
  syntax: '<length>',
  inherits: false,
  initialValue: '16px'
});

const el = document.body;
el.style.setProperty('--groesse', 'blau'); // keine gültige Länge
console.log(getComputedStyle(el).getPropertyValue('--groesse'));

16px

// Wichtig · Fallstricke

Nur einmal registrierbar: Wer denselben Namen ein zweites Mal registriert, bekommt eine InvalidModificationError-DOMException. Es gibt keine Methode, um eine Registrierung wieder aufzuheben. Bei Hot Reload oder in Modulen, die mehrfach laden, sollte man den Aufruf deshalb mit try/catch absichern.
SyntaxError wird geworfen, wenn der Name nicht mit -- beginnt, die Syntax-Zeichenkette ungültig ist, initialValue fehlt, obwohl syntax nicht '*' ist, oder der Startwert nicht zur Syntax passt bzw. nicht berechnungsunabhängig ist (z. B. em, var()).
Ein fehlendes inherits führt zu einem TypeError.
Kompatibilität: Chromium-Browser unterstützen die Methode seit Version 78, Safari seit 16.4, Firefox erst seit 128 (Juli 2024). In älteren Browsern verhalten sich die Eigenschaften wie gewöhnliche, nicht animierbare Custom Properties. Vorher mit 'registerProperty' in CSS prüfen.
Gibt es für denselben Namen sowohl @property im CSS als auch einen Aufruf von CSS.registerProperty(), gewinnt die Registrierung per JavaScript.
Die Registrierung gilt für das ganze Dokument und dringt auch in Shadow DOM ein. Namen deshalb eindeutig wählen, z. B. mit einem Präfix.

Siehe auch

CSS CSS.supports() CSS.escape() Element.animate() CSS numeric factory functions