HTMLStyleElement.media — Eigenschaft · JavaScript-Referenz

Signatur

HTMLStyleElement.media

Beschreibung

Die Eigenschaft media spiegelt das HTML-Attribut media eines <style>-Elements wider. Sie enthält einen String mit einer Media-Query-Liste, z. B. "print", "screen and (max-width: 600px)" oder "(prefers-color-scheme: dark)". Die Stilregeln im Element werden nur angewendet, wenn die Media-Query zutrifft.

Ist das Attribut nicht gesetzt, liefert die Eigenschaft einen leeren String "", was gleichbedeutend mit "all" ist: Die Stile gelten dann für alle Medien. Beim Schreiben wird das Attribut sofort aktualisiert, und der Browser bewertet die Media-Query neu – ohne dass der CSS-Inhalt neu geparst werden muss.

Typische Anwendungsfälle sind das dynamische Umschalten von Druck- oder Bildschirmstilen, das Aktivieren eines Dark-Mode-Stylesheets abhängig von einer Nutzereinstellung oder das gezielte Deaktivieren eines Stylesheets, indem man eine nie zutreffende Media-Query setzt (z. B. "not all").

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Beim Setzen: eine gültige Media-Query-Liste (kommagetrennt), z. B. `"screen, print"`. Wird in einen String umgewandelt und in das Attribut `media` geschrieben.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des media-Attributs. Leerer String, wenn das Attribut fehlt (entspricht "all").

Beispiele

Media-Query eines Style-Elements auslesen

// HTML: <style id="print-styles" media="print">body { color: black; }</style>
const style = document.getElementById('print-styles');
console.log(style.media);

const neu = document.createElement('style');
console.log(JSON.stringify(neu.media));

print ""

Druckvorschau auf dem Bildschirm simulieren

const printStyle = document.querySelector('style[media="print"]');
const toggle = document.querySelector('#preview-toggle');

toggle.addEventListener('change', () => {
  // Druckstile zusätzlich auf dem Bildschirm anwenden
  printStyle.media = toggle.checked ? 'screen, print' : 'print';
  console.log(`Aktive Media-Query: ${printStyle.media}`);
});

Aktive Media-Query: screen, print

Dark-Mode-Stylesheet per Nutzerwahl steuern

const darkStyle = document.createElement('style');
darkStyle.textContent = `body { background: #111; color: #eee; }`;
darkStyle.media = '(prefers-color-scheme: dark)';
document.head.append(darkStyle);

const setTheme = (theme) => {
  darkStyle.media = {
    auto: '(prefers-color-scheme: dark)',
    dark: 'all',
    light: 'not all' // Stylesheet effektiv deaktiviert
  }[theme];
};

setTheme('dark');
console.log(darkStyle.media);
console.log(window.matchMedia(darkStyle.media).matches);

all true

// Wichtig · Fallstricke

Kein Parsen-Fehler: Ungültige Media-Queries lösen keine Exception aus. Der Browser wertet sie als "not all" – die Stile werden dann stillschweigend nie angewendet. Mit window.matchMedia(style.media) lässt sich der Wert prüfen.
Leerer String ≠ keine Stile: "" bedeutet „gilt für alle Medien“. Um Stile abzuschalten, eignet sich eher style.disabled = true oder "not all".
Für eine strukturierte Bearbeitung einzelner Queries steht style.sheet.media (ein MediaList-Objekt mit appendMedium()/deleteMedium()) zur Verfügung; beide sind miteinander synchronisiert.
Veraltete Medientypen wie tv, handheld oder projection werden von modernen Browsern ignoriert; praktisch relevant sind nur all, screen und print plus Media-Features.
Kompatibilität: in allen Browsern unterstützt, seit den frühesten DOM-Versionen.

Siehe auch

HTMLHtmlElement.version HTMLStyleElement.sheet HTMLStyleElement.type HTMLStyleElement.blocking HTMLStyleElement.disabled