CSSStyleSheet.insertRule() — Methode · JavaScript-Referenz

Signatur

CSSStyleSheet.prototype.insertRule(rule, index)

Beschreibung

insertRule() fügt eine CSS-Regel direkt in das CSS-Objektmodell (CSSOM) eines Stylesheets ein. So lassen sich Stile zur Laufzeit ergänzen, ohne den Textinhalt eines <style>-Elements zu verändern. Die Regel wird geparst und landet an der angegebenen Position in sheet.cssRules.

Typische Einsatzfälle sind dynamisch erzeugte Themes, CSS-in-JS-Bibliotheken (die aus Performancegründen oft insertRule() statt Textmanipulation verwenden), @keyframes, die zur Laufzeit erzeugt werden, sowie Constructable Stylesheets (new CSSStyleSheet()), die über document.adoptedStyleSheets oder in Shadow-DOM-Wurzeln verwendet werden.

Die Position ist wichtig: Regeln weiter hinten gewinnen bei gleicher Spezifität. Ohne index wird die Regel an Position 0 eingefügt, also am Anfang, nicht am Ende. Um eine Regel anzuhängen, übergibt man sheet.cssRules.length.

Pro Aufruf ist genau eine Regel erlaubt. Dazu gehören auch At-Regeln wie @media, @keyframes oder @supports samt verschachtelten Regeln. Eine Zeichenkette mit mehreren Regeln führt zu einem SyntaxError.

Parameter

Name	Typ	Default	Beschreibung
$rule Pflicht	string		Genau eine vollständige CSS-Regel als Zeichenkette, z. B. `"h1 { color: red; }"` oder eine At-Regel wie `"@media (max-width: 600px) { ... }"`.
$index	number	0	Position in `cssRules`, an der die Regel eingefügt wird. Muss zwischen `0` und `cssRules.length` liegen. Ohne Angabe wird die Regel am Anfang eingefügt.

Rückgabewert

Typ

number

Beschreibung

Der Index der neu eingefügten Regel in sheet.cssRules.

Beispiele

Regel am Ende eines bestehenden Stylesheets anhängen

// Neues <style>-Element anlegen und an die Seite hängen
const style = document.createElement('style');
document.head.append(style);
const sheet = style.sheet;

const idx = sheet.insertRule('body { font-family: system-ui, sans-serif; }', sheet.cssRules.length);
sheet.insertRule('.hinweis { color: #b00; font-weight: bold; }', sheet.cssRules.length);

console.log(idx);
console.log(sheet.cssRules.length);
console.log(sheet.cssRules[1].cssText);

0 2 .hinweis { color: rgb(187, 0, 0); font-weight: bold; }

@keyframes zur Laufzeit erzeugen und verwenden

const sheet = document.head.appendChild(document.createElement('style')).sheet;

const erzeugeFadeIn = (name, dauerMs) => {
  sheet.insertRule(
    `@keyframes ${name} { from { opacity: 0; } to { opacity: 1; } }`,
    sheet.cssRules.length
  );
  sheet.insertRule(
    `.${name} { animation: ${name} ${dauerMs}ms ease-out both; }`,
    sheet.cssRules.length
  );
};

erzeugeFadeIn('einblenden', 400);
document.querySelector('main')?.classList.add('einblenden');
console.log(sheet.cssRules[0].constructor.name);

CSSKeyframesRule

Constructable Stylesheet für Shadow DOM

const sheet = new CSSStyleSheet();
sheet.insertRule(':host { display: block; padding: 1rem; }');
sheet.insertRule('button { border-radius: 4px; }', sheet.cssRules.length);

class MeineKarte extends HTMLElement {
  constructor() {
    super();
    const root = this.attachShadow({ mode: 'open' });
    root.adoptedStyleSheets = [sheet];
    root.innerHTML = '<button>Klick</button>';
  }
}
customElements.define('meine-karte', MeineKarte);
console.log(sheet.cssRules.length);

2

Fehlerbehandlung bei ungültigen Regeln

const sheet = document.head.appendChild(document.createElement('style')).sheet;

const sicherEinfuegen = (regel) => {
  try {
    return sheet.insertRule(regel, sheet.cssRules.length);
  } catch (err) {
    console.warn(`${err.name}: Regel abgelehnt`);
    return -1;
  }
};

sicherEinfuegen('p { margin: 0; }');
sicherEinfuegen('a { color: red; } b { color: blue; }'); // zwei Regeln
sicherEinfuegen('p { margin: 0; }', 99);

SyntaxError: Regel abgelehnt

// Wichtig · Fallstricke

Standard-Index ist 0: Ohne zweites Argument wird die Regel am Anfang eingefügt und kann so von späteren Regeln überschrieben werden. Zum Anhängen sheet.cssRules.length übergeben.
Ausnahmen: IndexSizeError, wenn index > cssRules.length ist. SyntaxError bei ungültiger oder mehrfacher Regel. HierarchyRequestError, wenn z. B. @import hinter normalen Regeln eingefügt würde. Bei Constructable Stylesheets ist @import ganz verboten.
Unbekannte Selektoren (z. B. herstellerspezifische Pseudoklassen) lösen einen SyntaxError aus. Deshalb browserspezifische Regeln einzeln und in try/catch einfügen.
Stylesheets von fremden Origins: Bei Stylesheets von einer anderen Domain ohne CORS-Freigabe wirft der Zugriff auf cssRules bzw. insertRule() einen SecurityError.
Per insertRule() eingefügte Regeln erscheinen nicht im textContent des <style>-Elements. Das ist in den Entwicklerwerkzeugen manchmal verwirrend. Wird textContent später neu gesetzt, gehen diese Regeln verloren.
Sicherheit: Keine ungeprüften Nutzereingaben in Regeln einbauen. CSS-Injection kann Layouts manipulieren oder über Attributselektoren mit url() Daten ausleiten (CSS-Exfiltration).
Die veraltete Methode addRule() nicht mehr verwenden. Für komplette Stylesheets sind replace()/replaceSync() bei Constructable Stylesheets oft praktischer.

Siehe auch

CSSStyleSheet CSSStyleSheet.deleteRule() CSSStyleSheet.cssRules CSSStyleSheet.replaceSync() Document.adoptedStyleSheets HTMLStyleElement.sheet