StyleSheetList.item() — Methode · JavaScript-Referenz

Signatur

StyleSheetList.prototype.item(index)

Beschreibung

Die Methode item() des Interfaces StyleSheetList liefert ein einzelnes Stylesheet aus der Liste, die du typischerweise über document.styleSheets oder shadowRoot.styleSheets bekommst. Die Liste enthält alle Stylesheets, die per <link rel="stylesheet"> oder <style> eingebunden sind, in der Reihenfolge, in der sie im Dokument stehen.

Statt item(i) kannst du auch die Klammerschreibweise styleSheets[i] verwenden. Der wichtigste Unterschied: Bei einem Index außerhalb des gültigen Bereichs gibt item() null zurück, die Klammerschreibweise dagegen undefined.

Einsatzzwecke sind zum Beispiel das Untersuchen von Stylesheets (Herkunft über href, Ein- und Ausschalten über disabled), das Auslesen oder Ändern von Regeln über cssRules sowie Werkzeuge wie Theme-Umschalter oder Analysen für CSS-Abdeckung.

Die Liste ist live: Kommen Stylesheets zum DOM hinzu oder werden welche entfernt, ändern sich Inhalt und length sofort. Stylesheets, die über document.adoptedStyleSheets eingebunden sind, gehören nicht zu dieser Liste.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Nullbasierte Position des gewünschten Stylesheets. Der Wert wird in eine vorzeichenlose 32-Bit-Ganzzahl umgewandelt (`unsigned long`).

Rückgabewert

Typ

CSSStyleSheet | null

Beschreibung

Das Stylesheet an Position index oder null, wenn index >= length ist.

Beispiele

Alle Stylesheets des Dokuments auflisten

const sheets = document.styleSheets;

for (let i = 0; i < sheets.length; i++) {
  const sheet = sheets.item(i);
  // Inline-<style>-Elemente haben kein href
  console.log(i, sheet.href ?? '(inline)', sheet.ownerNode.nodeName);
}

0 https://example.com/css/main.css LINK 1 (inline) STYLE

Vergleich: item() und Klammerschreibweise bei ungültigem Index

const sheets = document.styleSheets;
const outOfRange = sheets.length + 5;

console.log(sheets.item(outOfRange)); // null
console.log(sheets[outOfRange]);      // undefined

null undefined

Stylesheet anhand der URL finden und abschalten (Theme-Umschalter)

const findSheet = (fragment) => {
  const list = document.styleSheets;
  for (let i = 0; i < list.length; i++) {
    const sheet = list.item(i);
    if (sheet?.href?.includes(fragment)) return sheet;
  }
  return null;
};

const darkTheme = findSheet('dark.css');
if (darkTheme) {
  darkTheme.disabled = !darkTheme.disabled;
  console.log('Dunkles Theme aktiv:', !darkTheme.disabled);
}

Dunkles Theme aktiv: true

Regeln eines Stylesheets sicher auslesen

const first = document.styleSheets.item(0);

if (first) {
  try {
    const selectors = [...first.cssRules]
      .filter((rule) => rule instanceof CSSStyleRule)
      .map((rule) => rule.selectorText);
    console.log(selectors);
  } catch (err) {
    // Fremdes Stylesheet ohne CORS-Freigabe
    console.warn('Zugriff verweigert:', err.name);
  }
}

['body', '.header', '.nav a']

// Wichtig · Fallstricke

Rückgabe bei ungültigem Index: item() gibt null zurück, styleSheets[i] dagegen undefined. Das ist wichtig, wenn du strikt mit === undefined prüfst.
Negative Indizes: Werte wie -1 werden in eine große vorzeichenlose Zahl umgewandelt, das Ergebnis ist also null. Anders als Array.prototype.at() zählt item() nicht vom Ende her.
Kein echtes Array: StyleSheetList hat keine Methoden wie map oder filter. Mit Array.from(document.styleSheets) oder [...document.styleSheets] wandelst du die Liste um. Beachte dabei, dass so eine statische Kopie entsteht und keine Live-Liste mehr.
CORS: Bei Stylesheets von fremden Domains ohne crossorigin-Attribut und passende CORS-Header löst der Zugriff auf cssRules einen SecurityError aus. item() selbst funktioniert trotzdem.
Ladezeitpunkt: Ein <link>-Stylesheet, das noch lädt oder nicht geladen werden konnte, fehlt in der Liste möglicherweise. Warte deshalb auf das load-Ereignis des Elements.
Nicht enthalten: Stylesheets aus adoptedStyleSheets, alternative Stylesheets werden je nach Browser unterschiedlich behandelt, und Regeln aus @import erreichst du nur über CSSImportRule.styleSheet.
Kompatibilität: Wird seit Langem von allen Browsern unterstützt.

Siehe auch

StyleSheetList StyleSheetList.length Document.styleSheets CSSStyleSheet CSSStyleSheet.cssRules Document.adoptedStyleSheets CSSValueList.item()