HTMLElement.style — Eigenschaft · JavaScript-Referenz

Signatur

HTMLElement.style

Beschreibung

Die Eigenschaft style liefert ein CSSStyleProperties-Objekt (früher CSSStyleDeclaration), das ausschließlich die Deklarationen aus dem style-Attribut des Elements abbildet. Stile aus Stylesheets, <style>-Blöcken oder geerbte Werte sind hier nicht enthalten. Für den tatsächlich berechneten Wert nimmt man window.getComputedStyle().

Das Objekt ist „live“: Änderungen daran schreiben sich sofort ins style-Attribut zurück und umgekehrt. CSS-Eigenschaften werden in camelCase angesprochen (el.style.backgroundColor). Alternativ gibt es setProperty(), getPropertyValue() und removeProperty() mit der CSS-Schreibweise (background-color). Das ist bei CSS-Custom-Properties (--meine-farbe) der einzige Weg.

Formal ist die Eigenschaft schreibgeschützt, weil man das Objekt selbst nicht ersetzen kann. Weist man el.style aber einen String zu, leiten Browser das an el.style.cssText weiter. Dabei wird der gesamte Inline-Stil ersetzt.

Typische Einsatzfälle: dynamische Positionen und Größen (Drag & Drop, Animationen), das Setzen von CSS-Variablen aus JavaScript und das kurzfristige Überschreiben einzelner Werte. Für reine Zustandswechsel (sichtbar/unsichtbar, aktiv) ist es meist sauberer, Klassen über classList umzuschalten.

Rückgabewert

Typ

CSSStyleProperties

Beschreibung

Ein live gebundenes Objekt mit den Inline-Deklarationen des Elements. Nicht gesetzte Eigenschaften liefern den leeren String "".

Beispiele

Einzelne Eigenschaften setzen und lesen

const box = document.createElement('div');
box.style.backgroundColor = 'tomato';
box.style.width = '200px'; // Einheit nicht vergessen!
box.style.width = 200;      // ungültig: wird ignoriert

console.log(box.style.width);
console.log(box.style.color); // nicht inline gesetzt
console.log(box.getAttribute('style'));

200px background-color: tomato; width: 200px;

CSS-Custom-Properties mit setProperty

const root = document.documentElement;
root.style.setProperty('--akzent', '#0a84ff');
root.style.setProperty('margin', '0', 'important');

console.log(root.style.getPropertyValue('--akzent'));
console.log(root.style.getPropertyPriority('margin'));

root.style.removeProperty('--akzent');
console.log(root.style.getPropertyValue('--akzent') === '');

#0a84ff important true

Inline-Stil vs. berechneter Stil

// CSS im Stylesheet: .hinweis { color: red; }
const el = document.createElement('p');
el.className = 'hinweis';
document.body.append(el);

console.log(el.style.color);                   // Inline: leer
console.log(getComputedStyle(el).color);       // berechnet

rgb(255, 0, 0)

Element beim Ziehen der Maus folgen lassen

const marker = document.querySelector('#marker');
marker.style.position = 'fixed';

document.addEventListener('pointermove', (e) => {
  // transform statt left/top: performanter, kein Layout-Neuberechnen
  marker.style.transform = `translate(${e.clientX}px, ${e.clientY}px)`;
});

// Wichtig · Fallstricke

Nur Inline-Stile: el.style.display ist "", obwohl das Element per Stylesheet unsichtbar sein kann. Für echte Werte getComputedStyle() verwenden.
Einheiten: Zahlen ohne Einheit (el.style.width = 100) gelten als ungültig und werden stillschweigend verworfen. Eine Ausnahme sind einheitenlose Eigenschaften wie opacity oder zIndex.
Ungültige Werte werfen keinen Fehler, sondern werden einfach ignoriert. Der alte Wert bleibt erhalten.
Zuweisung eines Strings (el.style = 'color: red') bzw. cssText ersetzt alle bisherigen Inline-Deklarationen.
!important lässt sich nicht per Direktzuweisung setzen, nur über setProperty(name, wert, 'important'). Custom Properties (--x) gehen ebenfalls nur über setProperty bzw. getPropertyValue.
CSP: Das Setzen über das CSSOM (el.style.color = …) ist von style-src 'unsafe-inline'-Einschränkungen nicht betroffen. setAttribute('style', …) dagegen kann blockiert werden.
Performance: Wer viele Eigenschaften in einer Schleife ändert und dazwischen Layout-Werte liest (offsetHeight), erzwingt wiederholte Reflows. Deshalb Schreib- und Lesezugriffe bündeln oder lieber Klassen umschalten.
Der Rückgabetyp heißt in neueren Spezifikationen CSSStyleProperties. Ältere Browser und Dokumentationen nennen ihn CSSStyleDeclaration, die API ist identisch. Die Eigenschaft wird von allen Browsern unterstützt.

Siehe auch

window.getComputedStyle() CSSStyleDeclaration CSSStyleDeclaration.setProperty() CSSStyleDeclaration.cssText Element.classList Element.setAttribute() CSSStyleRule.style