MediaQueryList.removeListener() — Methode · JavaScript-Referenz

Signatur

MediaQueryList.prototype.removeListener(callback)

Beschreibung

Die Methode removeListener() des Interfaces MediaQueryList entfernt eine Rückruffunktion, die vorher mit addListener() registriert wurde. Danach wird die Funktion nicht mehr aufgerufen, wenn sich der Auswertungsstatus der Media Query ändert, also wenn etwa das Fenster schmaler wird oder der Nutzer zwischen hellem und dunklem Farbschema wechselt.

Die Methode ist veraltet. Seit MediaQueryList von EventTarget erbt, schreibt man stattdessen mql.removeEventListener("change", callback). Intern ist removeListener(cb) nur noch ein Alias für genau diesen Aufruf. Heute braucht man sie nur noch als Rückfall für alte Browser, zum Beispiel Safari vor Version 14.

Damit das Entfernen klappt, muss man dieselbe Funktionsreferenz übergeben wie beim Registrieren. Eine anonyme Pfeilfunktion, die erst beim Aufruf von removeListener() neu erzeugt wird, entfernt nichts. Wer Listener in Komponenten registriert (React, Vue, Web Components), sollte sie beim Aufräumen, also beim Unmount oder in disconnectedCallback, wieder entfernen. Sonst entstehen Speicherlecks und Aufrufe auf Komponenten, die es nicht mehr gibt.

Parameter

Name	Typ	Default	Beschreibung
$callback Pflicht	Function \| null		Die Funktion, die entfernt werden soll. Es muss dieselbe Referenz sein, die an `addListener()` bzw. `addEventListener("change", …)` übergeben wurde. Wird eine unbekannte Funktion oder `null` übergeben, passiert nichts.

Beispiele

Listener registrieren und wieder entfernen (Legacy-API)

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

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

mql.addListener(handleChange);

// Später, z. B. beim Verlassen der Ansicht:
mql.removeListener(handleChange);
console.log('Listener entfernt');

Listener entfernt

Moderne Variante mit Rückfall für alte Browser

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

const onSchemeChange = (e) => {
  document.documentElement.dataset.theme = e.matches ? 'dark' : 'light';
};

const subscribe = () => {
  if (typeof mql.addEventListener === 'function') {
    mql.addEventListener('change', onSchemeChange);
  } else {
    mql.addListener(onSchemeChange); // Safari < 14
  }
};

const unsubscribe = () => {
  if (typeof mql.removeEventListener === 'function') {
    mql.removeEventListener('change', onSchemeChange);
  } else {
    mql.removeListener(onSchemeChange);
  }
};

subscribe();
// ... beim Aufräumen:
unsubscribe();

Aufräumen in einer Web Component

class BreakpointBadge extends HTMLElement {
  #mql = window.matchMedia('(min-width: 1024px)');
  #update = (e) => {
    this.textContent = e.matches ? 'Desktop' : 'Mobil';
  };

  connectedCallback() {
    this.#update(this.#mql);
    this.#mql.addEventListener('change', this.#update);
  }

  disconnectedCallback() {
    // Gleiche Referenz entfernen, sonst entsteht ein Speicherleck
    this.#mql.removeEventListener('change', this.#update);
  }
}

customElements.define('breakpoint-badge', BreakpointBadge);

Typischer Fehler: neue Funktionsreferenz

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

mql.addListener((e) => console.log('Hochformat:', e.matches));

// Wirkungslos: Das ist eine NEUE Funktion, nicht die registrierte
mql.removeListener((e) => console.log('Hochformat:', e.matches));

// Richtig: Funktion in einer Variablen speichern und diese übergeben

// Wichtig · Fallstricke

Veraltet: Neuer Code sollte removeEventListener("change", callback) verwenden. removeListener() funktioniert zwar weiterhin in allen Browsern, wird aber nur noch aus Kompatibilitätsgründen mitgeliefert.
Kompatibilität: addEventListener/removeEventListener auf MediaQueryList gibt es erst ab Safari 14 (iOS 14). Wer ältere Safari-Versionen unterstützen muss, prüft vorher mit einer Feature-Erkennung (siehe Beispiel).
Referenzgleichheit: Nur exakt dieselbe Funktion wird entfernt. Mit bind() oder anonymen Funktionen erzeugte Callbacks muss man speichern.
Unter removeEventListener sind Listener pro Kombination aus Funktion und Capture-Flag registriert. removeListener() entfernt nur die Variante ohne Capture.
Eine Alternative zum manuellen Entfernen: addEventListener("change", cb, { signal }) zusammen mit einem AbortController. Ein einziges abort() entfernt dann alle so registrierten Listener.

Siehe auch

MediaQueryList.addListener() MediaQueryList Window.matchMedia() EventTarget.removeEventListener() MediaQueryList.matches