HTMLStyleElement.disabled — Eigenschaft · JavaScript-Referenz

Signatur

HTMLStyleElement.disabled

Beschreibung

Mit der Eigenschaft disabled eines HTMLStyleElement schalten Sie die CSS-Regeln eines eingebetteten <style>-Blocks per JavaScript ein oder aus. Das Element selbst bleibt dabei im DOM. Der Browser wendet nur die Regeln nicht mehr an. Das eignet sich für Theme-Umschalter (hell/dunkel), Druck- oder Debug-Stile und für Feature-Flags, die nur auf CSS-Ebene wirken.

Die Eigenschaft ist kein gespiegeltes HTML-Attribut. Ein <style disabled> im Markup bewirkt nichts. Intern leitet disabled an das zugehörige CSSStyleSheet weiter (styleElement.sheet.disabled). Beim Lesen erhalten Sie den Zustand dieses Stylesheets. Beim Setzen ändern Sie ihn direkt.

Gibt es noch kein zugehöriges Stylesheet, liefert der Getter immer false und der Setter hat keine Wirkung. Das ist etwa der Fall, wenn das Element noch nicht im Dokument eingehängt ist. Setzen Sie disabled deshalb erst, nachdem das Element eingefügt wurde.

Parameter

Name	Typ	Default	Beschreibung
$value	boolean	false	Neuer Wert beim Setzen: `true` deaktiviert das Stylesheet, `false` aktiviert es wieder. Andere Werte werden nach den üblichen Regeln in `boolean` umgewandelt.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das zugehörige Stylesheet deaktiviert ist, sonst false. Ebenfalls false, wenn noch kein Stylesheet existiert (sheet === null).

Beispiele

Dunkles Theme per Button umschalten

// HTML: <style id="dark-theme">body { background:#111; color:#eee; }</style>
//       <button id="toggle">Theme wechseln</button>
const darkTheme = document.getElementById('dark-theme');
const toggle = document.getElementById('toggle');

// Standardmäßig helles Theme
darkTheme.disabled = true;

toggle.addEventListener('click', () => {
  darkTheme.disabled = !darkTheme.disabled;
  console.log(`Dunkles Theme aktiv: ${!darkTheme.disabled}`);
});

Dunkles Theme aktiv: true

Zusammenhang mit sheet.disabled

const style = document.createElement('style');
style.textContent = '.debug * { outline: 1px solid red; }';
document.head.append(style);

style.disabled = true;
console.log(style.sheet.disabled); // gleicher Zustand

style.sheet.disabled = false;
console.log(style.disabled);

true false

Fallstrick: Setzen vor dem Einfügen wirkt nicht

const style = document.createElement('style');
style.textContent = 'p { color: red; }';

style.disabled = true;      // noch kein Stylesheet vorhanden, wird ignoriert
console.log(style.disabled); // false

document.head.append(style);
console.log(style.disabled); // false, die Regeln werden angewendet

style.disabled = true;       // jetzt wirksam
console.log(style.disabled);

false false true

// Wichtig · Fallstricke

Kein HTML-Attribut: <style disabled> im Markup wird ignoriert. Den Zustand setzen Sie ausschließlich über JavaScript. Bei HTMLLinkElement.disabled ist das anders, dort wird das Attribut gespiegelt.
Zustand geht verloren: Wird das <style>-Element aus dem DOM entfernt und wieder eingefügt, oder ändert sich sein textContent, erzeugt der Browser ein neues CSSStyleSheet. Es ist wieder aktiviert (disabled === false).
Ohne Stylesheet keine Wirkung: Ist sheet gleich null, zum Beispiel bei nicht eingehängten Elementen oder einem nicht passenden type-Attribut, bewirkt der Setter nichts.
Soll der Zustand über ein Neuladen der Seite hinaus erhalten bleiben (etwa eine Theme-Wahl), speichern Sie ihn separat, z. B. in localStorage.
Die Eigenschaft wird in allen modernen Browsern seit Langem unterstützt.

Siehe auch

HTMLStyleElement HTMLStyleElement.sheet StyleSheet.disabled HTMLLinkElement.disabled CSSStyleSheet HTMLOptGroupElement.disabled HTMLOptionElement.label