HTMLStyleElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLStyleElement extends HTMLElement

Beschreibung

Das Interface HTMLStyleElement steht für ein <style>-Element, das CSS direkt im Dokument einbettet. Es erbt alle Eigenschaften und Methoden von HTMLElement und ergänzt einige eigene. Instanzen erhält man über document.createElement("style") oder indem man vorhandene Elemente abfragt, etwa mit document.querySelector("style").

Die wichtigsten eigenen Eigenschaften sind:

sheet (nur lesbar): das zugehörige CSSStyleSheet-Objekt bzw. null, solange das Element nicht im Dokument hängt.
media: die Media Query, für die das Stylesheet gilt (z. B. "print" oder "(max-width: 600px)").
disabled: true schaltet das Stylesheet ab, ohne das Element zu entfernen.
blocking: eine DOMTokenList, mit der man angibt, ob das Stylesheet das Rendern blockiert ("render").
type (veraltet): MIME-Typ, heute überflüssig, weil text/css der einzige sinnvolle Wert ist.

Gebraucht wird das Interface vor allem, um zur Laufzeit CSS einzuschleusen, etwa für Themes, CSS-in-JS-Bibliotheken, Widgets oder Styles innerhalb eines Shadow DOM. Außerdem kann man bestehende Stylesheets gezielt ein- und ausschalten. Über sheet.insertRule() lassen sich Regeln einzeln einfügen, ohne den Textinhalt neu zu parsen.

Rückgabewert

Typ

HTMLStyleElement

Beschreibung

Wird von document.createElement("style") oder von DOM-Abfragen wie querySelector("style") zurückgegeben.

Beispiele

Style-Element erzeugen und CSS einfügen

const style = document.createElement("style");
style.textContent = `
  .hinweis { background: #fffae6; padding: 1rem; border-left: 4px solid orange; }
`;
document.head.append(style);

console.log(style instanceof HTMLStyleElement);
console.log(style.sheet.cssRules.length);

true 1

Regeln dynamisch über sheet.insertRule() ergänzen

const style = document.createElement("style");
document.head.append(style); // sheet existiert erst nach dem Einhängen

const sheet = style.sheet;
sheet.insertRule("body { font-family: system-ui, sans-serif; }", 0);
sheet.insertRule(".btn:hover { opacity: 0.8; }", sheet.cssRules.length);

console.log([...sheet.cssRules].map((r) => r.cssText));

["body { font-family: system-ui, sans-serif; }", ".btn:hover { opacity: 0.8; }"]

Dark-Mode-Theme per disabled umschalten

const darkTheme = document.createElement("style");
darkTheme.id = "dark-theme";
darkTheme.textContent = "body { background: #121212; color: #eee; }";
darkTheme.disabled = true; // zunächst aus
document.head.append(darkTheme);

const toggleTheme = () => {
  darkTheme.disabled = !darkTheme.disabled;
  console.log(`Dark Mode: ${darkTheme.disabled ? "aus" : "an"}`);
};

document.querySelector("#theme-toggle")?.addEventListener("click", toggleTheme);
toggleTheme();

Dark Mode: an

Druck-Styles über media einschränken

const printStyle = document.createElement("style");
printStyle.media = "print";
printStyle.textContent = "nav, footer { display: none; }";
document.head.append(printStyle);

console.log(printStyle.media);
console.log(printStyle.sheet.media.mediaText);

print print

// Wichtig · Fallstricke

sheet ist null, solange das Element nicht im Dokument (oder in einem Shadow Root) hängt. Erst einhängen, dann insertRule() aufrufen.
disabled vor dem Einhängen: Ältere Browser haben einen vor dem Einhängen gesetzten Wert ignoriert. Sicherer ist es, disabled erst nach dem Einfügen zu setzen.
Wenn man textContent neu setzt, wird das komplette Stylesheet neu geparst, und Regeln, die per insertRule() eingefügt wurden, gehen verloren. Bei häufigen Änderungen lieber mit sheet arbeiten oder Constructable Stylesheets (new CSSStyleSheet() plus adoptedStyleSheets) verwenden.
Sicherheit: Nutzereingaben nie ungeprüft in textContent eines Style-Elements schreiben. CSS-Injection kann Daten abgreifen (z. B. über Attribut-Selektoren mit url()-Anfragen) oder die Oberfläche manipulieren. Mit einer strengen Content Security Policy (style-src ohne 'unsafe-inline') werden eingebettete Style-Elemente blockiert, außer sie tragen eine passende nonce (style.nonce = "...").
type ist veraltet und sollte nicht mehr gesetzt werden. Das Attribut scoped wurde aus dem Standard entfernt; für gekapselte Styles verwendet man heute Shadow DOM oder @scope.
Kompatibilität: sheet, media und disabled funktionieren in allen modernen Browsern. blocking ist neuer und wird noch nicht überall unterstützt.

Siehe auch

HTMLSourceElement HTMLHtmlElement HTMLTableElement HTMLTimeElement HTMLTitleElement