MediaQueryList — Schnittstelle · JavaScript-Referenz

Signatur

interface MediaQueryList extends EventTarget

Beschreibung

Ein MediaQueryList-Objekt enthält Informationen über eine CSS-Media-Query, die auf das aktuelle Dokument angewendet wird. Man erzeugt es nie direkt, sondern immer über window.matchMedia(query). Das Objekt erlaubt zwei Arten der Auswertung: sofort über die Eigenschaft matches und ereignisgesteuert über das change-Event, das ausgelöst wird, sobald sich das Ergebnis der Query ändert.

Typische Einsatzfälle sind responsive Logik in JavaScript (z. B. anderes Menüverhalten auf Mobilgeräten), das Erkennen von Nutzerpräferenzen wie prefers-color-scheme (Dark Mode) oder prefers-reduced-motion sowie das Reagieren auf Druckansicht, Ausrichtung oder Pixeldichte. Im Gegensatz zu einem resize-Listener feuert change nur beim tatsächlichen Umschalten der Bedingung – das ist deutlich effizienter.

Wichtige Mitglieder:

matches (nur lesbar, boolean) – true, wenn das Dokument der Query aktuell entspricht.
media (nur lesbar, string) – die serialisierte Media Query.
onchange – Handler-Eigenschaft für das change-Event (Ereignisobjekt: MediaQueryListEvent mit matches und media).
addListener() / removeListener() – veraltete Aliase; stattdessen addEventListener("change", …) verwenden.

Parameter

Name	Typ	Default	Beschreibung
$query Pflicht	string		Media-Query-String, der an `window.matchMedia()` übergeben wird, z. B. `"(max-width: 600px)"` oder `"(prefers-color-scheme: dark)"`. Das Interface selbst hat keinen öffentlichen Konstruktor.

Rückgabewert

Typ

MediaQueryList

Beschreibung

Von window.matchMedia() zurückgegebenes Objekt mit den Eigenschaften matches, media und dem change-Event.

Beispiele

Instanz erzeugen und sofort auswerten

const mql = window.matchMedia('(max-width: 600px)');

console.log(mql.media);   // serialisierte Query
console.log(mql.matches); // aktueller Zustand

if (mql.matches) {
  document.body.classList.add('mobile');
}

(max-width: 600px) true // bei einem Viewport ≤ 600px

Dark Mode per change-Event verfolgen

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

const applyTheme = (isDark) => {
  document.documentElement.dataset.theme = isDark ? 'dark' : 'light';
  console.log(`Theme: ${isDark ? 'dunkel' : 'hell'}`);
};

// Initialzustand setzen – change feuert NICHT beim Registrieren
applyTheme(darkQuery.matches);

darkQuery.addEventListener('change', (event) => {
  applyTheme(event.matches);
});

Theme: hell Theme: dunkel // nach Umstellen der Systemeinstellung

Listener sauber wieder entfernen (on-Property und removeEventListener)

const mql = window.matchMedia('(orientation: landscape)');

const onOrientation = (e) => {
  console.log(e.matches ? 'Querformat' : 'Hochformat');
};

mql.addEventListener('change', onOrientation);

// Später, z. B. beim Unmount einer Komponente:
mql.removeEventListener('change', onOrientation);

// Alternative über die Handler-Eigenschaft:
mql.onchange = onOrientation;
mql.onchange = null; // entfernt den Handler wieder

Animationen bei reduzierter Bewegung abschalten

const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)');

const scrollToTop = () => {
  window.scrollTo({
    top: 0,
    behavior: reduceMotion.matches ? 'auto' : 'smooth'
  });
};

document.querySelector('#nach-oben')?.addEventListener('click', scrollToTop);

// Wichtig · Fallstricke

Kein Initial-Event: change wird nur bei einer Änderung ausgelöst. Den Startzustand immer separat über matches auswerten.
Veraltete API: addListener()/removeListener() sind deprecated. Safari vor Version 14 unterstützt allerdings nur diese; für sehr alte Browser ggf. Fallback: mql.addEventListener ? mql.addEventListener('change', fn) : mql.addListener(fn).
Referenz behalten: Zum Entfernen des Listeners muss dieselbe Funktionsreferenz übergeben werden – anonyme Pfeilfunktionen lassen sich nicht wieder abmelden. Alternativ ein AbortSignal über die signal-Option nutzen.
Ungültige Queries werfen keinen Fehler; media liefert dann "not all" und matches ist false.
Performance: matchMedia mit change ist einem resize-Listener mit manueller Breitenprüfung fast immer vorzuziehen.
In Node.js oder beim Server-Side-Rendering existiert window.matchMedia nicht – vorher auf typeof window !== 'undefined' prüfen. In Test-Umgebungen wie jsdom muss es gemockt werden.

Siehe auch

Window.matchMedia() MediaQueryList.matches MediaQueryList.media MediaQueryListEvent EventTarget.addEventListener()