HTMLLinkElement.media — Eigenschaft · JavaScript-Referenz

Signatur

HTMLLinkElement.media

Beschreibung

Die Eigenschaft media des HTMLLinkElement-Interfaces spiegelt das HTML-Attribut media wider. Sie enthält einen String mit einer oder mehreren durch Kommas getrennten Medientypen bzw. Media Queries, z. B. "print", "screen and (min-width: 768px)" oder "(prefers-color-scheme: dark)". Ist das Attribut nicht gesetzt, liefert die Eigenschaft einen leeren String – die Ressource gilt dann für alle Medien (entspricht "all").

Am häufigsten nutzt man media bei Stylesheets (rel="stylesheet"), um CSS nur unter bestimmten Bedingungen anzuwenden, etwa ein Druck-Stylesheet oder ein Dark-Mode-Theme. Auch bei rel="preload" und rel="icon" kann der Browser das Attribut berücksichtigen, um Ressourcen nur bei passender Media Query zu laden bzw. zu verwenden.

Weil die Eigenschaft beschreibbar ist, lässt sie sich per JavaScript ändern: Das Setzen wirkt sofort, der Browser wertet die neue Media Query aus und aktiviert oder deaktiviert das Stylesheet entsprechend. Ein bekanntes Muster ist das nicht blockierende Laden von CSS: Man setzt zunächst media="print" und schaltet nach dem load-Event auf "all" um.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Beim Setzen: eine gültige Media-Query-Liste, z. B. `"screen, print"` oder `"(max-width: 600px)"`. Wird unverändert ins `media`-Attribut geschrieben.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des media-Attributs als String; leerer String, wenn das Attribut fehlt.

Beispiele

Media-Wert eines Stylesheets auslesen

// HTML: <link id="druck" rel="stylesheet" href="print.css" media="print">
const link = document.getElementById('druck');
console.log(link.media);

// Alle Stylesheets mit ihren Media Queries auflisten
document.querySelectorAll('link[rel="stylesheet"]').forEach((el) => {
  console.log(el.href, '→', el.media || 'all');
});

print https://example.com/print.css → print

CSS nicht blockierend nachladen

const loadCss = (href) => new Promise((resolve, reject) => {
  const link = document.createElement('link');
  link.rel = 'stylesheet';
  link.href = href;
  link.media = 'print'; // blockiert das Rendern nicht
  link.addEventListener('load', () => {
    link.media = 'all'; // nach dem Laden für alle Medien aktivieren
    resolve(link);
  });
  link.addEventListener('error', reject);
  document.head.append(link);
});

await loadCss('/css/extras.css');
console.log('Stylesheet aktiv');

Stylesheet aktiv

Dark-Mode-Theme manuell umschalten

// HTML: <link id="dark" rel="stylesheet" href="dark.css" media="(prefers-color-scheme: dark)">
const darkLink = document.getElementById('dark');

const setTheme = (mode) => {
  darkLink.media = {
    dark: 'all',                             // immer dunkel
    light: 'not all',                        // nie anwenden
    system: '(prefers-color-scheme: dark)'   // Systemeinstellung folgen
  }[mode];
};

setTheme('dark');
console.log(darkLink.media);

all

Prüfen, ob die Media Query aktuell zutrifft

const link = document.querySelector('link[rel="stylesheet"][media]');
const aktiv = window.matchMedia(link.media || 'all').matches;
console.log(`Stylesheet ${link.href} aktiv: ${aktiv}`);

Stylesheet https://example.com/print.css aktiv: false

// Wichtig · Fallstricke

Kein Validieren: Beim Setzen findet keine Syntaxprüfung statt. Eine ungültige Media Query wird als not all behandelt – das Stylesheet greift dann nie, ohne dass ein Fehler geworfen wird.
Laden ≠ Anwenden: Browser laden Stylesheets mit nicht passender Media Query in der Regel trotzdem herunter (nur mit niedrigerer Priorität und ohne Render-Blockade). media spart also keine Bandbreite bei Stylesheets.
Die Eigenschaft liefert den Attribut-String; für eine strukturierte Liste nutzt man link.sheet.media (ein MediaList-Objekt), das erst nach dem Laden verfügbar ist.
Leerer String bedeutet „alle Medien“, nicht „keine“. Zum Deaktivieren eignet sich "not all" oder link.disabled = true.
Die Auswertung von media bei rel="preload" wird von allen modernen Browsern unterstützt, ältere Versionen ignorieren sie teils.

Siehe auch

HTMLLinkElement.hreflang HTMLLinkElement.rel HTMLLinkElement.as HTMLLinkElement.href HTMLLinkElement.relList