CSSStyleSheet — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSStyleSheet extends StyleSheet

Beschreibung

CSSStyleSheet ist die Objektdarstellung eines CSS-Stylesheets im CSSOM. Jedes über <link rel="stylesheet"> oder <style> eingebundene Stylesheet steht als CSSStyleSheet in document.styleSheets bereit. Über element.sheet kommt man an das Stylesheet eines bestimmten Elements.

Die wichtigsten Mitglieder:

cssRules – eine live-aktualisierte CSSRuleList mit allen Regeln (z. B. CSSStyleRule, CSSMediaRule).
ownerRule – die @import-Regel, falls das Stylesheet importiert wurde, sonst null.
insertRule(rule, index) – fügt eine Regel an Position index ein (Standard 0) und gibt den Index zurück.
deleteRule(index) – entfernt die Regel an der angegebenen Position.
replace(text) / replaceSync(text) – ersetzen den kompletten Inhalt eines konstruierten Stylesheets (asynchron mit Promise oder synchron).

Mit dem Konstruktor new CSSStyleSheet(options) lassen sich konstruierbare Stylesheets anlegen, die nicht an ein DOM-Element gebunden sind. Man hängt sie über document.adoptedStyleSheets oder shadowRoot.adoptedStyleSheets ein. Das ist vor allem für Web Components nützlich: Ein Stylesheet kann in vielen Shadow Roots gleichzeitig verwendet werden, ohne dass das CSS jedes Mal neu geparst wird.

Typische Einsatzfälle sind dynamische Themes, zur Laufzeit erzeugte Regeln (etwa für CSS-in-JS-Bibliotheken), das Auswerten vorhandener Styles in Entwicklerwerkzeugen und gemeinsam genutzte Styles für Web Components.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionen für den Konstruktor `new CSSStyleSheet(options)`.
$options.baseURL	string	URL des Dokuments	Basis-URL, gegen die relative URLs im Stylesheet (z. B. in `url()`) aufgelöst werden.
$options.media	string \| MediaList	""	Media-Query-Liste, für die das Stylesheet gilt, z. B. `"screen and (min-width: 600px)"`.
$options.disabled	boolean	false	Legt fest, ob das Stylesheet anfangs deaktiviert ist.

Rückgabewert

Typ

CSSStyleSheet

Beschreibung

Der Konstruktor liefert ein neues, leeres, konstruiertes Stylesheet, das über adoptedStyleSheets eingebunden werden kann.

Beispiele

Konstruierbares Stylesheet anlegen und dem Dokument zuweisen

const sheet = new CSSStyleSheet({ media: 'screen' });
sheet.replaceSync(`
  body { font-family: system-ui, sans-serif; }
  .hinweis { color: #b00; font-weight: bold; }
`);

// Vorhandene adoptierte Stylesheets beibehalten
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

console.log(sheet.cssRules.length);

2

Regeln zur Laufzeit einfügen und löschen

const style = document.createElement('style');
document.head.append(style);
const sheet = style.sheet; // CSSStyleSheet

const idx = sheet.insertRule('.aktiv { outline: 2px solid orange; }', sheet.cssRules.length);
console.log(`Regel an Index ${idx}:`, sheet.cssRules[idx].cssText);

// Regel später wieder entfernen
sheet.deleteRule(idx);
console.log('Anzahl Regeln:', sheet.cssRules.length);

Regel an Index 0: .aktiv { outline: orange solid 2px; } Anzahl Regeln: 0

Gemeinsames Stylesheet für Web Components

const sharedSheet = new CSSStyleSheet();
sharedSheet.replaceSync(':host { display: block; padding: 1rem; border: 1px solid #ccc; }');

class InfoBox extends HTMLElement {
  constructor() {
    super();
    const root = this.attachShadow({ mode: 'open' });
    root.adoptedStyleSheets = [sharedSheet]; // wird nur einmal geparst
    root.innerHTML = '<slot></slot>';
  }
}
customElements.define('info-box', InfoBox);

// Änderung wirkt sofort in allen Instanzen
sharedSheet.insertRule(':host { background: #f5f5f5; }', 1);

Alle Regeln der Seite auslesen (mit CORS-Schutz)

const listRules = () => {
  for (const sheet of document.styleSheets) {
    try {
      for (const rule of sheet.cssRules) {
        console.log(sheet.href ?? 'inline', '→', rule.cssText);
      }
    } catch (err) {
      // Fremd-Stylesheets ohne CORS werfen SecurityError
      console.warn('Kein Zugriff auf', sheet.href, err.name);
    }
  }
};
listRules();

inline → body { margin: 0px; } Kein Zugriff auf https://cdn.example.com/lib.css SecurityError

// Wichtig · Fallstricke

Cross-Origin: Wer cssRules eines Stylesheets von einer fremden Herkunft liest, bekommt einen SecurityError, außer der Server liefert passende CORS-Header und das <link> hat crossorigin. Solche Zugriffe am besten in try/catch kapseln.
replace()/replaceSync() gibt es nur für konstruierte Stylesheets. Bei <style>- oder <link>-Stylesheets werfen sie einen NotAllowedError. @import-Regeln werden in konstruierten Stylesheets nicht unterstützt und ignoriert.
insertRule() nimmt pro Aufruf genau eine Regel an. Ungültiges CSS führt zu einem SyntaxError, ein ungültiger Index zu einem IndexSizeError. Ohne Index wird an Position 0 eingefügt, also mit der niedrigsten Priorität in der Kaskade.
adoptedStyleSheets ist in modernen Browsern ein veränderbares Array. Eine direkte Zuweisung ersetzt aber alle bisherigen Einträge, deshalb besser mit Spread-Syntax anhängen.
Konstruierbare Stylesheets gibt es erst seit Chrome 73, Firefox 101 und Safari 16.4. Für ältere Browser braucht man ein <style>-Element als Rückfalllösung.
Die veralteten Methoden addRule()/removeRule() und die Eigenschaft rules sollten nicht mehr verwendet werden. Stattdessen insertRule(), deleteRule() und cssRules nutzen.
Sicherheit: Nutzereingaben nie ungeprüft in CSS-Regeln einsetzen. CSS-Injection kann Daten abgreifen (etwa über Attributselektoren mit url()) oder die Oberfläche manipulieren.

Siehe auch

StyleSheet Document.styleSheets Document.adoptedStyleSheets ShadowRoot.adoptedStyleSheets CSSStyleSheet.prototype.insertRule() CSSStyleSheet.prototype.replace()