CSSStyleDeclaration.setProperty() — Methode · JavaScript-Referenz

Signatur

CSSStyleDeclaration.prototype.setProperty(propertyName, value, priority)

Beschreibung

setProperty() setzt oder überschreibt eine CSS-Deklaration in einem CSSStyleDeclaration-Objekt. Solche Objekte bekommt man typischerweise über element.style (Inline-Stile) oder über CSSStyleRule.style (Regeln in einem Stylesheet). Der Eigenschaftsname wird in der CSS-Schreibweise angegeben, also mit Bindestrichen (background-color), nicht in camelCase.

Die Methode ist der einzige direkte Weg, um CSS Custom Properties (--hauptfarbe) per JavaScript zu setzen, weil diese nicht als Eigenschaft von element.style existieren. Außerdem kann man nur mit setProperty() eine Deklaration mit !important versehen – über den dritten Parameter "important".

Ist der übergebene Wert ungültig, wird er stillschweigend verworfen: Es gibt keinen Fehler, und der bisherige Wert bleibt erhalten. Ein leerer String oder null als Wert entfernt die Deklaration – entspricht also removeProperty().

Parameter

Name	Typ	Default	Beschreibung
$propertyName Pflicht	string		Name der CSS-Eigenschaft in Bindestrich-Schreibweise, z. B. `"font-size"` oder eine Custom Property wie `"--abstand"`.
$value	string \| null	""	Neuer Wert als CSS-Text, z. B. `"12px"`. Leerer String oder `null` entfernt die Deklaration. Darf kein `!important` enthalten.
$priority	string	""	`"important"` setzt die Deklaration mit `!important`; `""` (oder `undefined`) ohne Priorität. Andere Werte führen dazu, dass nichts gesetzt wird.

Beispiele

Inline-Stil eines Elements setzen

const box = document.querySelector('.box');

// Bindestrich-Schreibweise, nicht camelCase
box.style.setProperty('background-color', 'rebeccapurple');
box.style.setProperty('border-radius', '8px');

console.log(box.getAttribute('style'));

background-color: rebeccapurple; border-radius: 8px;

CSS Custom Property für ein Theme ändern

const root = document.documentElement;

const setTheme = (dark) => {
  root.style.setProperty('--bg', dark ? '#121212' : '#ffffff');
  root.style.setProperty('--text', dark ? '#eeeeee' : '#222222');
};

setTheme(true);
console.log(getComputedStyle(root).getPropertyValue('--bg').trim());

#121212

Mit !important setzen und Priorität prüfen

const hinweis = document.querySelector('#hinweis');

hinweis.style.setProperty('display', 'none', 'important');

console.log(hinweis.style.getPropertyValue('display'));
console.log(hinweis.style.getPropertyPriority('display'));

none important

Regel in einem Stylesheet ändern und ungültige Werte

const sheet = new CSSStyleSheet();
sheet.replaceSync('.btn { padding: 4px; }');
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const rule = sheet.cssRules[0];
rule.style.setProperty('padding', '12px 24px');
rule.style.setProperty('padding', 'banane'); // ungültig -> ignoriert

console.log(rule.style.padding);

12px 24px

// Wichtig · Fallstricke

Keine camelCase-Namen: setProperty('backgroundColor', 'red') tut nichts. Richtig ist 'background-color'. Custom Properties sind zudem case-sensitiv (--Farbe ≠ --farbe).
Kein !important im Wert: setProperty('color', 'red !important') ist ungültig und wird ignoriert – den dritten Parameter 'important' verwenden.
Stilles Scheitern: Ungültige Werte werfen keinen Fehler. Wer sicher sein will, prüft danach mit getPropertyValue() oder vorab mit CSS.supports(eigenschaft, wert).
Zahlen ohne Einheit (z. B. setProperty('width', 100)) sind für Längen ungültig; Einheit immer mitgeben. Custom Properties nehmen dagegen fast jeden Wert an.
Das von getComputedStyle() gelieferte Objekt ist schreibgeschützt; setProperty() darauf wirft eine NoModificationAllowedError.
Sicherheit/CSP: Das Setzen über element.style ist auch unter einer strengen CSP ohne 'unsafe-inline' erlaubt, anders als ein per setAttribute('style', …) gesetzter String. Werte aus Benutzereingaben sollten trotzdem geprüft werden (z. B. bei url()).
Kompatibilität: in allen modernen Browsern unterstützt; Custom Properties ab etwa 2016/2017 (nicht im Internet Explorer).

Siehe auch

CSSStyleDeclaration CSSStyleDeclaration.getPropertyValue() CSSStyleDeclaration.removeProperty() CSSStyleDeclaration.getPropertyPriority() HTMLElement.style Window.getComputedStyle() CSS.supports()