CSS — Schnittstelle · JavaScript-Referenz

Signatur

interface CSS

Beschreibung

CSS ist keine Klasse, von der man Instanzen erzeugt, sondern ein Namensraum mit rein statischen Methoden und Eigenschaften. Ein Aufruf wie new CSS() ist nicht möglich und wirft einen TypeError. Alle Funktionen werden direkt über das globale Objekt angesprochen, etwa CSS.supports() oder CSS.escape().

Die wichtigsten Mitglieder:

CSS.supports(property, value) bzw. CSS.supports(conditionText) – prüft wie @supports in JavaScript, ob der Browser eine Deklaration oder Bedingung versteht. Der Rückgabewert ist ein boolean.
CSS.escape(ident) – maskiert eine Zeichenkette, sodass sie gefahrlos als Teil eines CSS-Selektors verwendet werden kann (z. B. IDs, die mit Ziffern beginnen oder Sonderzeichen enthalten).
CSS.registerProperty(definition) – registriert eine benutzerdefinierte Eigenschaft (Custom Property) mit Syntax, Vererbung und Startwert (CSS Properties and Values API, Houdini).
Fabrikfunktionen der CSS Typed OM wie CSS.px(), CSS.em(), CSS.percent(), CSS.deg(), CSS.number() – erzeugen typisierte CSSUnitValue-Objekte.
CSS.highlights – ein HighlightRegistry für die CSS Custom Highlight API.
CSS.paintWorklet – Zugriff auf das Paint-Worklet (Houdini; nur in Chromium-Browsern und nur in sicheren Kontexten).

Typische Einsatzfälle sind die Feature-Erkennung vor dem Einsatz neuer CSS-Funktionen (progressive Verbesserung), das sichere Zusammenbauen von Selektoren für querySelector() aus Benutzer- oder Serverdaten sowie das animierbare Registrieren von Custom Properties.

Parameter

Name	Typ	Beschreibung
$property	string	Bei `CSS.supports(property, value)`: Name der CSS-Eigenschaft, z. B. `"display"`.
$value	string	Bei `CSS.supports(property, value)`: zu prüfender Wert, z. B. `"grid"`.
$conditionText	string	Bei `CSS.supports(conditionText)`: vollständige Bedingung wie in `@supports`, z. B. `"(display: grid) and (gap: 1rem)"` oder `"selector(:has(a))"`.
$ident	string	Bei `CSS.escape(ident)`: zu maskierende Zeichenkette für die Verwendung in Selektoren.
$definition	{ name: string, syntax?: string, inherits: boolean, initialValue?: string }	Bei `CSS.registerProperty()`: Beschreibung der Custom Property. `name` muss mit `--` beginnen.

Rückgabewert

Typ

boolean | string | void | CSSUnitValue

Beschreibung

Abhängig von der Methode: supports() liefert boolean, escape() einen string, registerProperty() undefined, die Einheiten-Fabriken ein CSSUnitValue.

Beispiele

Feature-Erkennung mit CSS.supports()

// Zwei Aufrufformen: Eigenschaft/Wert oder komplette Bedingung
const hasGrid = CSS.supports('display', 'grid');
const hasHas = CSS.supports('selector(:has(img))');
const hasContainer = CSS.supports('(container-type: inline-size)');

document.documentElement.classList.toggle('no-has', !hasHas);
console.log({ hasGrid, hasHas, hasContainer });

{ hasGrid: true, hasHas: true, hasContainer: true }

Selektor sicher mit CSS.escape() bauen

// IDs aus Serverdaten können mit Ziffern beginnen oder Sonderzeichen enthalten
const ids = ['123-artikel', 'foo.bar', 'a#b'];

for (const id of ids) {
  const selector = `#${CSS.escape(id)}`;
  console.log(selector);
  const el = document.querySelector(selector); // wirft keinen SyntaxError
}

#\31 23-artikel #foo\.bar #a\#b

Animierbare Custom Property registrieren

// Ohne Registrierung kann der Browser --winkel nicht interpolieren
if ('registerProperty' in CSS) {
  CSS.registerProperty({
    name: '--winkel',
    syntax: '<angle>',
    inherits: false,
    initialValue: '0deg'
  });
}

const box = document.querySelector('.box');
box.style.background = 'conic-gradient(from var(--winkel), red, blue)';
box.animate([{ '--winkel': '0deg' }, { '--winkel': '360deg' }], {
  duration: 2000,
  iterations: Infinity
});

Typisierte Werte mit der CSS Typed OM

const el = document.querySelector('.box');

if (el.attributeStyleMap) {
  el.attributeStyleMap.set('width', CSS.px(240));
  el.attributeStyleMap.set('opacity', CSS.number(0.8));

  const breite = el.attributeStyleMap.get('width');
  console.log(breite.value, breite.unit);
  console.log(CSS.percent(50).toString());
}

240 px 50%

// Wichtig · Fallstricke

Kein Konstruktor: new CSS() wirft einen TypeError; alle Mitglieder sind statisch.
Kompatibilität: CSS.supports() und CSS.escape() funktionieren in allen modernen Browsern. CSS.registerProperty() ist Baseline seit 2024 (Firefox ab 128). Die Typed-OM-Fabriken (CSS.px() usw.) fehlen in Firefox, CSS.paintWorklet gibt es nur in Chromium. Vor der Nutzung immer mit 'methode' in CSS prüfen.
CSS.supports() prüft nur die Syntax, nicht, ob die Funktion vollständig oder fehlerfrei umgesetzt ist. Bei der Form mit einem Argument muss die Bedingung eingeklammert sein: CSS.supports('display: grid') ohne Klammern gibt in aktuellen Browsern false zurück (einige ältere Engines waren toleranter).
Sicherheit: CSS.escape() dient nur dazu, Selektoren und Bezeichner zu maskieren. Es schützt nicht vor XSS in HTML oder vor Injektionen in beliebigen CSS-Werten (z. B. url()). Für HTML weiterhin textContent oder eine Bereinigung verwenden.
CSS.registerProperty() wirft eine InvalidModificationError-DOMException, wenn derselbe Name zweimal registriert wird, und einen SyntaxError, wenn initialValue nicht zu syntax passt. Alternativ geht die Registrierung deklarativ per @property.

Siehe auch

CSS.supports() CSS.escape() CSS.registerProperty() CSS.highlights CSSUnitValue CSSStyleDeclaration Document.querySelector() Window.matchMedia()