MediaQueryListEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface MediaQueryListEvent extends Event

Beschreibung

MediaQueryListEvent ist das Ereignisobjekt, das ein Listener bekommt, wenn sich das Ergebnis einer Media Query ändert. Eine solche MediaQueryList erzeugt man mit window.matchMedia(). Das Event wird genau dann ausgelöst, wenn die Abfrage von „trifft zu“ auf „trifft nicht zu“ wechselt oder umgekehrt, zum Beispiel beim Überschreiten eines Breakpoints, beim Umschalten des Dunkelmodus im System oder beim Drehen des Geräts.

Die Schnittstelle erbt von Event und hat zwei zusätzliche, schreibgeschützte Eigenschaften:

matches (boolean): true, wenn das Dokument der Media Query jetzt entspricht.
media (string): die Media Query als serialisierte Zeichenkette, z. B. "(max-width: 600px)".

Damit können Sie in JavaScript auf Layout- oder Präferenzänderungen reagieren, ohne das resize-Event abzufragen und selbst Breite oder Höhe zu vergleichen. Das ist sparsamer und genauer, weil der Browser nur bei tatsächlichen Zustandswechseln benachrichtigt. Typische Einsatzfälle sind das Umschalten zwischen mobiler und Desktop-Navigation, das Berücksichtigen von prefers-color-scheme und prefers-reduced-motion sowie das Nachladen von Komponenten ab einer bestimmten Bildschirmgröße.

In der Regel erzeugen Sie die Instanzen nicht selbst, sondern der Browser liefert sie. Für Tests oder zum künstlichen Auslösen gibt es aber den Konstruktor new MediaQueryListEvent(type, options).

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, in der Praxis immer `"change"` (nur für den Konstruktor).
$options	{ matches?: boolean, media?: string, bubbles?: boolean, cancelable?: boolean, composed?: boolean }	{ matches: false, media: "" }	Optionales Initialisierungsobjekt (nur für den Konstruktor). `matches` und `media` legen die gleichnamigen Eigenschaften fest, dazu kommen die üblichen `EventInit`-Felder.

Rückgabewert

Typ

MediaQueryListEvent

Beschreibung

Eine neue Instanz mit den schreibgeschützten Eigenschaften matches (boolean) und media (string).

Beispiele

Auf Breakpoint-Wechsel reagieren

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

const handleChange = (event) => {
  // event ist ein MediaQueryListEvent
  document.body.classList.toggle('mobile', event.matches);
  console.log(`${event.media} trifft zu: ${event.matches}`);
};

mql.addEventListener('change', handleChange);

// Anfangszustand einmal setzen – beim Laden wird kein change-Event ausgelöst
document.body.classList.toggle('mobile', mql.matches);

(max-width: 600px) trifft zu: true // nach Verkleinern des Fensters

Dunkelmodus des Systems live übernehmen

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

const applyTheme = ({ matches }) => {
  document.documentElement.dataset.theme = matches ? 'dark' : 'light';
  console.log('Theme:', document.documentElement.dataset.theme);
};

applyTheme(darkQuery); // MediaQueryList hat ebenfalls .matches
darkQuery.addEventListener('change', applyTheme);

Theme: dark // nach Umschalten in den Systemeinstellungen

Listener mit AbortController wieder entfernen

const controller = new AbortController();
const motionQuery = window.matchMedia('(prefers-reduced-motion: reduce)');

motionQuery.addEventListener('change', (e) => {
  console.log('Animationen reduzieren:', e.matches);
}, { signal: controller.signal });

// Später, z. B. beim Abbau einer Komponente:
controller.abort();

Event im Test künstlich erzeugen

const fakeEvent = new MediaQueryListEvent('change', {
  matches: true,
  media: '(orientation: landscape)'
});

console.log(fakeEvent instanceof Event, fakeEvent.media, fakeEvent.matches);

true "(orientation: landscape)" true

// Wichtig · Fallstricke

Kein Event beim Start: change wird nur bei einem Zustandswechsel ausgelöst. Den Anfangszustand müssen Sie selbst über mql.matches auswerten.
Veraltete API: mql.addListener() und removeListener() sind veraltet. Verwenden Sie addEventListener('change', …). Safari unterstützt addEventListener auf MediaQueryList erst ab Version 14. Wenn Sie ältere Versionen unterstützen müssen, prüfen Sie vorher, ob die Methode vorhanden ist, und greifen Sie sonst auf addListener zurück.
Die Eigenschaft onchange von MediaQueryList ist eine Alternative, erlaubt aber nur einen einzigen Handler.
event.media ist die vom Browser serialisierte Form der Abfrage. Leerzeichen und Groß-/Kleinschreibung können sich vom Original unterscheiden. Vergleichen Sie deshalb nicht blind auf exakte Gleichheit.
Heben Sie eine Referenz auf die MediaQueryList auf, damit Sie den Listener später zuverlässig wieder entfernen können und kein Speicherleck entsteht.

Siehe auch

Event MediaEncryptedEvent MediaRecorderErrorEvent MediaQueryList MediaStreamEvent