MediaQueryList.media — Eigenschaft · JavaScript-Referenz

Signatur

MediaQueryList.media

Beschreibung

Die Eigenschaft media eines MediaQueryList-Objekts enthält die Medienabfrage, die beim Aufruf von window.matchMedia() übergeben wurde, als serialisierten String. Sie ist schreibgeschützt. Die Abfrage lässt sich also nachträglich nicht ändern. Brauchen Sie eine andere Abfrage, erzeugen Sie mit matchMedia() ein neues Objekt.

Nützlich ist media vor allem dann, wenn mehrere MediaQueryList-Objekte denselben change-Handler teilen. Über event.media oder mql.media erkennen Sie dann, welche Abfrage gerade umgeschaltet hat. Auch beim Debuggen und Loggen hilft die Eigenschaft.

Wichtig: Der Browser gibt den String serialisiert zurück, also in normalisierter Form. Leerzeichen und Groß-/Kleinschreibung können vom Original abweichen. Ist die Abfrage ungültig, liefert media den String "not all".

Rückgabewert

Typ

string

Beschreibung

Die serialisierte Medienabfrage, z. B. "(min-width: 768px)". Bei einer ungültigen Abfrage ist der Wert "not all".

Beispiele

Medienabfrage auslesen

const mql = window.matchMedia('(max-width: 600px)');
console.log(mql.media);
console.log(mql.matches ? 'Mobil-Layout' : 'Desktop-Layout');

(max-width: 600px) Desktop-Layout

Gemeinsamer change-Handler für mehrere Breakpoints

const queries = ['(max-width: 599px)', '(min-width: 600px) and (max-width: 1023px)', '(min-width: 1024px)'];

const handleChange = (event) => {
  // event.media entspricht mql.media des auslösenden Objekts
  if (event.matches) {
    console.log(`Aktiver Breakpoint: ${event.media}`);
  }
};

for (const q of queries) {
  const mql = window.matchMedia(q);
  mql.addEventListener('change', handleChange);
  if (mql.matches) console.log(`Start-Breakpoint: ${mql.media}`);
}

Start-Breakpoint: (min-width: 1024px)

Normalisierung und ungültige Abfragen erkennen

const normalized = window.matchMedia('(MIN-WIDTH:500px)');
console.log(normalized.media);

const invalid = window.matchMedia('foo bar baz');
console.log(invalid.media);

const isValidQuery = (q) => window.matchMedia(q).media !== 'not all';
console.log(isValidQuery('(prefers-color-scheme: dark)'));

(min-width: 500px) not all true

Dark-Mode-Status protokollieren

const darkMql = window.matchMedia('(prefers-color-scheme: dark)');

const logScheme = ({ media, matches }) => {
  console.log(`${media} → ${matches ? 'aktiv' : 'inaktiv'}`);
};

logScheme(darkMql);
darkMql.addEventListener('change', logScheme);

(prefers-color-scheme: dark) → inaktiv

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie mql.media = '...' bewirkt nichts. Im Strict Mode wirft sie einen TypeError. Für eine andere Abfrage rufen Sie matchMedia() neu auf.
Serialisierung: Vergleichen Sie media nicht per String-Gleichheit mit Ihrer Originaleingabe. Der Browser normalisiert Leerzeichen und Kleinschreibung. Das genaue Ergebnis kann sich zwischen Browsern leicht unterscheiden. Besser ist es, die Referenz auf das MediaQueryList-Objekt zu vergleichen.
Ungültige Abfragen lösen keinen Fehler aus. Sie liefern stattdessen media === "not all" und matches === false.
Kompatibilität: Die Eigenschaft wird in allen modernen Browsern unterstützt. addEventListener('change', …) auf MediaQueryList funktioniert in Safari erst ab Version 14. Ältere Safari-Versionen brauchen das veraltete addListener().

Siehe auch

MediaQueryListEvent.matches MediaQueryList.matches MediaQueryListEvent.media MediaList.mediaText CSSMediaRule.media