MediaQueryList.addListener() — Methode · JavaScript-Referenz

Signatur

MediaQueryList.prototype.addListener(callback)

Beschreibung

addListener() hängt eine Callback-Funktion an ein MediaQueryList-Objekt, das du über window.matchMedia() bekommst. Die Funktion wird immer dann aufgerufen, wenn die Media Query von „trifft zu“ auf „trifft nicht zu“ wechselt oder umgekehrt, z. B. wenn der Viewport eine Breakpoint-Grenze überschreitet oder jemand das Farbschema des Betriebssystems umstellt.

Die Methode ist veraltet. Seit MediaQueryList von EventTarget erbt, ist sie nur noch ein Alias für addEventListener("change", callback). In neuem Code solltest du direkt addEventListener() bzw. die Eigenschaft onchange verwenden. Das bringt dir zusätzlich Optionen wie once oder signal (AbortController).

Sinnvoll ist addListener() heute nur noch als Fallback für alte Browser, vor allem für Safari vor Version 14, wo MediaQueryList noch kein EventTarget war. Der Callback bekommt ein MediaQueryListEvent mit den Eigenschaften matches und media. In sehr alten Implementierungen war das stattdessen das MediaQueryList-Objekt selbst. Beide haben aber matches und media.

Parameter

Name	Typ	Default	Beschreibung
$callback Pflicht	((event: MediaQueryListEvent) => void) \| null		Funktion, die bei jeder Änderung des Media-Query-Status aufgerufen wird. Sie bekommt ein `MediaQueryListEvent` mit `matches` (boolean) und `media` (string). Bei `null` passiert nichts.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Breakpoint-Wechsel überwachen (veraltete Schreibweise)

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

const handleChange = (event) => {
  console.log(event.matches ? 'Mobile Ansicht' : 'Desktop-Ansicht');
};

// Anfangszustand einmal selbst prüfen – der Listener feuert nur bei Änderungen
handleChange(mql);

mql.addListener(handleChange);

// Später wieder abmelden:
// mql.removeListener(handleChange);

Desktop-Ansicht // nach Verkleinern des Fensters unter 768px: Mobile Ansicht

Moderner Ersatz mit addEventListener

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

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

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

// Alternativ über die on-Property:
// darkMode.onchange = applyTheme;

Theme: light // nach Umschalten des OS auf Dark Mode: Theme: dark

Kompatibler Helfer mit Fallback für altes Safari

const watchMedia = (query, callback) => {
  const mql = window.matchMedia(query);
  callback(mql);

  if (typeof mql.addEventListener === 'function') {
    mql.addEventListener('change', callback);
    return () => mql.removeEventListener('change', callback);
  }
  // Fallback für Safari < 14
  mql.addListener(callback);
  return () => mql.removeListener(callback);
};

const stop = watchMedia('(orientation: portrait)', (e) => {
  console.log('Hochformat:', e.matches);
});

// Aufräumen, z. B. beim Unmount einer Komponente
// stop();

Hochformat: false

// Wichtig · Fallstricke

Veraltet: Verwende addEventListener('change', …). addListener() ist in modernen Browsern nur noch ein Alias und bleibt aus Kompatibilitätsgründen erhalten.
Kein Aufruf beim Registrieren: Der Callback läuft erst bei einer Änderung. Den Anfangszustand musst du selbst über mql.matches abfragen.
Abmelden: removeListener() braucht dieselbe Funktionsreferenz. Inline-Arrow-Functions kannst du deshalb nicht mehr entfernen. Das führt in Single-Page-Apps leicht zu Speicherlecks.
Gleiche Funktion mehrfach: Wie bei addEventListener wird dieselbe Funktion nur einmal registriert.
Referenz behalten: Speichere das MediaQueryList-Objekt in einer Variablen. Wenn du matchMedia() bei jedem Aufruf neu ausführst, entstehen unabhängige Objekte, und removeListener() greift dann nicht.
Kompatibilität: Safari/iOS vor Version 14 kennt nur addListener(). Wenn du diese Versionen unterstützen musst, prüfe zuerst, ob addEventListener vorhanden ist.

Siehe auch

new XMLSerializer() MediaQueryList.removeListener() MediaList.item() MediaList.deleteMedium() MediaList.toString()