MediaQueryList.matches — Eigenschaft · JavaScript-Referenz

Signatur

MediaQueryList.matches

Beschreibung

Die Eigenschaft matches eines MediaQueryList-Objekts zeigt an, ob die zugrunde liegende Medienabfrage für das aktuelle Dokument gerade zutrifft. Das Objekt erhält man über window.matchMedia(query). Der Wert ist live: Er wird bei jedem Lesen neu ausgewertet und passt sich an, wenn sich z. B. die Fenstergröße, die Ausrichtung oder das bevorzugte Farbschema ändert.

Typische Einsatzfälle sind responsives Verhalten in JavaScript (etwa ein anderes Navigationsmenü unter einer bestimmten Breite), das Auswerten von Benutzereinstellungen wie prefers-color-scheme oder prefers-reduced-motion sowie das Erkennen von Druckansicht oder Eingabegeräten (pointer: coarse, hover: hover).

Für eine einmalige Prüfung reicht es, matches direkt zu lesen. Soll auf Änderungen reagiert werden, registriert man einen Listener für das change-Event der MediaQueryList; das übergebene MediaQueryListEvent besitzt ebenfalls eine matches-Eigenschaft mit dem neuen Zustand. Das ist deutlich effizienter als ein Abfragen im resize-Handler.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Dokument die Medienabfrage momentan erfüllt, andernfalls false. Schreibzugriffe werden ignoriert (im Strict Mode: TypeError).

Beispiele

Einmalige Prüfung der Viewport-Breite

const mobileQuery = window.matchMedia('(max-width: 768px)');

if (mobileQuery.matches) {
  console.log('Mobile Ansicht aktiv');
} else {
  console.log('Desktop-Ansicht aktiv');
}

Mobile Ansicht aktiv // bei Fensterbreite ≤ 768px

Dunkles Farbschema erkennen und live nachführen

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

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

// Startzustand setzen
applyTheme(darkQuery.matches);

// Auf Änderungen der Systemeinstellung reagieren
darkQuery.addEventListener('change', (event) => {
  applyTheme(event.matches);
});

Theme: dark // wenn das System dunkles Design nutzt

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);

Listener sauber wieder entfernen

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

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

landscape.addEventListener('change', onOrientationChange);
console.log('Aktuell Querformat?', landscape.matches);

// Später, z. B. beim Zerstören einer Komponente:
landscape.removeEventListener('change', onOrientationChange);

Aktuell Querformat? true

// Wichtig · Fallstricke

Nur lesbar: Eine Zuweisung wie mql.matches = true bewirkt nichts bzw. wirft im Strict Mode einen TypeError.
Ungültige Abfragen: Eine syntaktisch fehlerhafte Medienabfrage führt nicht zu einem Fehler, sondern ergibt media = "not all" und matches = false. Tippfehler bleiben so leicht unbemerkt.
Nicht in resize abfragen: Statt bei jedem resize-Event matchMedia() aufzurufen, ein MediaQueryList-Objekt einmal anlegen und dessen change-Event nutzen.
Ältere Safari-Versionen (< 14): Dort unterstützt MediaQueryList kein addEventListener; stattdessen das veraltete addListener()/removeListener() verwenden, falls diese Versionen noch relevant sind.
SSR / Node.js: window.matchMedia gibt es nur im Browser. In serverseitigem Code oder Tests (z. B. jsdom) vorher auf Existenz prüfen oder mocken.
In iframes bezieht sich die Abfrage auf den Viewport des iframe, nicht auf das Hauptfenster.

Siehe auch

MediaKeySystemAccess.keySystem MediaQueryList.media MediaQueryListEvent.matches MediaQueryListEvent.media Request.cache