CSSStyleSheet.deleteRule() — Methode · JavaScript-Referenz

Signatur

CSSStyleSheet.prototype.deleteRule(index)

Beschreibung

deleteRule() löscht zur Laufzeit eine einzelne CSS-Regel aus einem Stylesheet. Du gibst dabei die Position der Regel in der Liste sheet.cssRules an. Alle Regeln dahinter rücken um eine Stelle nach vorn, die Liste ist also sofort neu durchnummeriert.

Gebraucht wird die Methode vor allem, wenn Styles per JavaScript gesteuert werden: bei dynamischen Themes, bei Regeln, die mit insertRule() nur vorübergehend eingefügt wurden, bei CSS-in-JS-Bibliotheken und bei Constructable Stylesheets (new CSSStyleSheet()) im Shadow DOM. Anders als beim Umschreiben von <style>-Inhalten muss der Browser dabei nicht das ganze Stylesheet neu parsen.

Weil sich die Positionen nach jedem Löschen verschieben, solltest du mehrere Regeln von hinten nach vorn löschen. Alternativ merkst du dir den Rückgabewert von insertRule() nicht als feste ID, sondern suchst die Regel vor dem Löschen erneut, zum Beispiel über selectorText.

Verschachtelte Regeln wie @media oder @supports haben eine eigene Methode CSSGroupingRule.deleteRule(). Damit löschst du Regeln innerhalb dieser Gruppe.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Position der zu löschenden Regel in `sheet.cssRules`, beginnend bei 0. Der Wert muss kleiner als `cssRules.length` sein.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück. Das Stylesheet selbst wird direkt verändert.

Beispiele

Vorübergehend eingefügte Regel wieder entfernen

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

// Regel einfügen – insertRule liefert den Index zurück
const idx = sheet.insertRule('body { background: #fffae6; }', sheet.cssRules.length);
console.log(sheet.cssRules.length);

// Nach 2 Sekunden wieder entfernen
setTimeout(() => {
  sheet.deleteRule(idx);
  console.log(sheet.cssRules.length);
}, 2000);

1 0

Regel anhand des Selektors finden und löschen

const removeRuleBySelector = (sheet, selector) => {
  // Von hinten nach vorn, damit sich die Positionen nicht verschieben
  for (let i = sheet.cssRules.length - 1; i >= 0; i--) {
    const rule = sheet.cssRules[i];
    if (rule instanceof CSSStyleRule && rule.selectorText === selector) {
      sheet.deleteRule(i);
    }
  }
};

const sheet = document.querySelector('#theme').sheet;
removeRuleBySelector(sheet, '.dark-mode');
console.log([...sheet.cssRules].map(r => r.cssText));

["body { margin: 0px; }"]

Constructable Stylesheet im Shadow DOM

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  :host { display: block; }
  .badge { color: red; }
`);

const host = document.createElement('div');
document.body.append(host);
const shadow = host.attachShadow({ mode: 'open' });
shadow.adoptedStyleSheets = [sheet];

// Die zweite Regel (.badge) entfernen
sheet.deleteRule(1);
console.log(sheet.cssRules.length, sheet.cssRules[0].cssText);

1 :host { display: block; }

Fehlerbehandlung bei ungültigem Index

const sheet = new CSSStyleSheet();
sheet.replaceSync('p { color: blue; }');

try {
  sheet.deleteRule(5);
} catch (err) {
  console.log(err.name);
}

IndexSizeError

// Wichtig · Fallstricke

Positionen verschieben sich: Nach jedem Löschen rücken die folgenden Regeln nach vorn. Wenn du in einer Schleife von vorn nach hinten löschst, überspringst du Regeln. Lösche deshalb immer rückwärts.
Ungültiger Index: Ist index größer oder gleich cssRules.length, wirft die Methode eine DOMException vom Typ IndexSizeError. Ein negativer Wert wird wegen der Umwandlung in unsigned long zu einer sehr großen Zahl und führt deshalb zum selben Fehler.
Stylesheets von fremden Domains (CORS): Bei Stylesheets, die von einer anderen Herkunft ohne passende CORS-Header geladen wurden, löst schon der Zugriff auf cssRules einen SecurityError aus. Solche Stylesheets kannst du also nicht per deleteRule() bearbeiten.
Namespace-Regeln: Eine @namespace-Regel lässt sich nur löschen, wenn das Stylesheet nur noch aus @import- und @namespace-Regeln besteht. Sonst gibt es einen InvalidStateError.
Constructable Stylesheets: Solange replace() noch läuft, führt deleteRule() zu einem NotAllowedError.
Veraltete Alternative: removeRule() ist eine alte Variante aus dem Internet Explorer und sollte nicht mehr benutzt werden.
Browser-Unterstützung: deleteRule() funktioniert in allen gängigen Browsern. Constructable Stylesheets gibt es in Safari erst ab Version 16.4.

Siehe auch

CSSStyleSheet.insertRule() CSSStyleSheet.cssRules CSSStyleSheet.replaceSync() CSSStyleSheet CSSGroupingRule.deleteRule() Document.adoptedStyleSheets new VTTCue()