IntersectionObserver.unobserve() — Methode · JavaScript-Referenz

Signatur

IntersectionObserver.prototype.unobserve(target)

Beschreibung

Mit unobserve() entfernen Sie ein bestimmtes Element aus der Liste der Ziele eines IntersectionObserver. Danach werden für dieses Element keine Einträge mehr an den Callback geliefert. Der Observer selbst bleibt aktiv und beobachtet alle übrigen Ziele weiter.

Typische Anwendungsfälle sind einmalige Aktionen: Lazy Loading von Bildern, das Nachladen von Inhalten, einmalige Einblend-Animationen oder das Erfassen von Sichtbarkeit (Impression-Tracking). Sobald das Ereignis eingetreten ist, wird das Element per unobserve() abgemeldet. Das spart Rechenzeit und verhindert, dass die Aktion mehrfach ausgeführt wird.

Soll der Observer alle Ziele auf einmal verlieren, ist disconnect() die richtige Wahl. unobserve() eignet sich dagegen für eine feine Steuerung pro Element – etwa wenn einzelne Listeneinträge aus dem DOM entfernt werden.

Parameter

Name	Typ	Default	Beschreibung
$target Pflicht	Element		Das Element, dessen Beobachtung beendet werden soll. Ist das Element gar nicht registriert, passiert nichts – es wird kein Fehler ausgelöst.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück.

Beispiele

Lazy Loading: Bild nach dem Laden abmelden

const observer = new IntersectionObserver((entries, obs) => {
  entries.forEach((entry) => {
    if (!entry.isIntersecting) return;
    const img = entry.target;
    img.src = img.dataset.src; // echtes Bild laden
    obs.unobserve(img);        // nur einmal nötig
    console.log(`Geladen: ${img.dataset.src}`);
  });
}, { rootMargin: '200px' });

document.querySelectorAll('img[data-src]').forEach((img) => observer.observe(img));

Geladen: /bilder/foto-1.jpg

Einmalige Einblend-Animation

const reveal = new IntersectionObserver((entries) => {
  for (const entry of entries) {
    if (entry.isIntersecting) {
      entry.target.classList.add('sichtbar');
      reveal.unobserve(entry.target);
    }
  }
}, { threshold: 0.25 });

document.querySelectorAll('.reveal').forEach((el) => reveal.observe(el));

Element vor dem Entfernen aus dem DOM abmelden

const tracker = new IntersectionObserver((entries) => {
  entries.forEach((e) => console.log(e.target.id, e.isIntersecting));
});

const karte = document.querySelector('#karte-42');
tracker.observe(karte);

const entfernen = (el) => {
  tracker.unobserve(el); // Referenz im Observer freigeben
  el.remove();
};

entfernen(karte);
tracker.unobserve(karte); // erneuter Aufruf: kein Fehler

// Wichtig · Fallstricke

Einträge, die bereits in der Warteschlange stehen, können nach unobserve() unter Umständen nicht mehr zugestellt werden; verlassen Sie sich nicht darauf, dass ein letzter Callback-Aufruf erfolgt.
Der Aufruf mit einem nicht beobachteten Element ist ein stiller No-Op. Wird jedoch kein Element übergeben (z. B. null nach einem fehlgeschlagenen querySelector), wirft der Browser einen TypeError.
Innerhalb des Callbacks steht der Observer als zweites Argument zur Verfügung – so lässt sich unobserve() aufrufen, ohne eine äußere Variable zu benötigen.
Zum Aufräumen aller Ziele (z. B. beim Unmount einer Komponente) ist disconnect() effizienter als viele einzelne unobserve()-Aufrufe.
Kompatibilität: in allen aktuellen Browsern verfügbar; Internet Explorer wird nicht unterstützt (nur per Polyfill).

Siehe auch

IntersectionObserver.takeRecords() IntersectionObserver.observe() IntersectionObserver.disconnect() MutationObserver.observe() ResizeObserver.unobserve()