MediaQueryListEvent.matches — Eigenschaft · JavaScript-Referenz

Signatur

MediaQueryListEvent.matches

Beschreibung

Die schreibgeschützte Eigenschaft matches des Interfaces MediaQueryListEvent gibt an, ob das Dokument die zugehörige Media Query zum Zeitpunkt des Events erfüllt. Das Event wird beim change-Event einer MediaQueryList ausgelöst, also jedes Mal, wenn sich der Zustand der Abfrage ändert, z. B. wenn der Viewport eine Breakpoint-Grenze überschreitet oder jemand das Farbschema des Betriebssystems umstellt.

Man braucht matches, um in JavaScript auf Änderungen von Media Queries zu reagieren, ohne ständig auf resize zu hören. Typische Einsätze sind Wechsel zwischen Mobil- und Desktop-Layout, die Umsetzung von prefers-color-scheme (Dunkelmodus) oder prefers-reduced-motion sowie das Laden oder Abbauen von Komponenten abhängig von der Bildschirmgröße.

Der Wert entspricht dem Wert von MediaQueryList.matches direkt nach der Änderung. Die zugehörige Abfrage als Zeichenkette steht in MediaQueryListEvent.media. Beachte: Das change-Event wird beim Registrieren nicht ausgelöst. Den Anfangszustand musst du deshalb selbst über MediaQueryList.matches auslesen.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Dokument der Media Query nach der Änderung entspricht, sonst false. Nur lesbar.

Beispiele

Auf einen Breakpoint reagieren

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

const handleChange = (event) => {
  if (event.matches) {
    console.log('Mobiles Layout aktiv');
  } else {
    console.log('Desktop-Layout aktiv');
  }
};

mql.addEventListener('change', handleChange);

// Anfangszustand selbst prüfen – 'change' wird nicht sofort ausgelöst
handleChange(mql);

Desktop-Layout aktiv // nach Verkleinern des Fensters unter 600px: Mobiles Layout aktiv

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: ${matches ? 'dark' : 'light'}`);
};

applyTheme(darkQuery);
darkQuery.addEventListener('change', applyTheme);

Theme: light // nach Umschalten im Betriebssystem: Theme: dark

Animationen bei reduzierter Bewegung abschalten und Listener wieder entfernen

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

motionQuery.addEventListener('change', (event) => {
  console.log(event.media, '->', event.matches);
  document.body.classList.toggle('no-animations', event.matches);
}, { signal: controller.signal });

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

(prefers-reduced-motion: reduce) -> true

// Wichtig · Fallstricke

Kein Startwert per Event: Das change-Event wird nur bei einer Änderung ausgelöst. Den Anfangszustand liest du über MediaQueryList.matches aus. Da MediaQueryList ebenfalls matches und media besitzt, kannst du denselben Handler direkt damit aufrufen.
Veraltete API: Ältere Safari-Versionen (vor 14) kennen addEventListener auf MediaQueryList nicht. Dort gibt es nur die veralteten Methoden addListener() bzw. removeListener(). Falls nötig, mit typeof mql.addEventListener === 'function' prüfen und auf diese Methoden ausweichen.
Referenz behalten: Speichere die MediaQueryList in einer Variablen. Nur so lässt sich der Listener später mit removeEventListener entfernen, und nur so bleibt das Objekt zuverlässig erhalten.
Bei Abfragen wie (max-width: 600px) und (min-width: 600px) treffen an der Grenze von genau 600px beide zu. Wähle die Breakpoints deshalb so, dass sich die Bereiche nicht überschneiden, z. B. (min-width: 601px).
matches ist schreibgeschützt. Eine Zuweisung wird stillschweigend ignoriert und löst im Strict Mode einen TypeError aus.

Siehe auch

MediaKeyMessageEvent.messageType MediaQueryListEvent.media MediaQueryList.matches MediaQueryList.media HIDInputReportEvent.data