IntersectionObserver.rootMargin — Eigenschaft · JavaScript-Referenz

Signatur

IntersectionObserver.rootMargin

Beschreibung

Die schreibgeschützte Eigenschaft rootMargin eines IntersectionObserver gibt die Abstände zurück, um die das Begrenzungsrechteck des Roots (des Root-Elements oder des Viewports) vor der Schnittberechnung erweitert (positive Werte) oder verkleinert (negative Werte) wird. Die Syntax entspricht der CSS-Eigenschaft margin: ein bis vier Werte in der Reihenfolge oben, rechts, unten, links.

Festgelegt wird der Wert ausschließlich über die Option rootMargin beim Konstruktor-Aufruf new IntersectionObserver(callback, { rootMargin }). Die Eigenschaft liefert den normalisierten Wert zurück: Auch wenn du nur "50px" angibst, liest du immer vier Werte aus, z. B. "50px 50px 50px 50px". Ohne Angabe gilt "0px 0px 0px 0px".

Typische Einsatzgebiete:

Lazy Loading / Vorladen: Mit positivem Rand (z. B. "200px 0px") wird der Callback ausgelöst, bevor ein Element sichtbar wird. So können Bilder oder Daten rechtzeitig geladen werden.
Endloses Scrollen: Ein Sentinel-Element am Listenende lädt schon vorher nach.
Scroll-Spy / aktive Abschnitte: Mit negativen Werten (z. B. "-40% 0px -55% 0px") wird nur ein schmaler Streifen im Viewport als „sichtbar“ gewertet.

Erlaubt sind nur die Einheiten px und %. Prozentwerte beziehen sich auf die Größe des Roots: oben/unten auf dessen Höhe, links/rechts auf dessen Breite.

Rückgabewert

Typ

string

Beschreibung

Normalisierter String mit immer vier Werten in px oder % (oben, rechts, unten, links), z. B. "0px 0px 0px 0px" oder "10% 0px 10% 0px".

Beispiele

Wert setzen und normalisiert auslesen

const observer = new IntersectionObserver(() => {}, {
  rootMargin: '50px 20px'
});

console.log(observer.rootMargin);

const standard = new IntersectionObserver(() => {});
console.log(standard.rootMargin);

50px 20px 50px 20px 0px 0px 0px 0px

Bilder 300px vor dem Sichtbarwerden nachladen

const lazyObserver = new IntersectionObserver((entries, obs) => {
  for (const entry of entries) {
    if (!entry.isIntersecting) continue;
    const img = entry.target;
    img.src = img.dataset.src; // echte Bildquelle setzen
    obs.unobserve(img);        // nur einmal laden
  }
}, {
  rootMargin: '300px 0px' // 300px Vorlauf oben und unten
});

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

console.log(`Vorladebereich: ${lazyObserver.rootMargin}`);

Vorladebereich: 300px 0px 300px 0px

Scroll-Spy mit negativem Rand

// Nur ein Streifen zwischen 40 % und 45 % der Viewport-Höhe zählt als sichtbar
const spy = new IntersectionObserver((entries) => {
  for (const entry of entries) {
    if (!entry.isIntersecting) continue;
    const id = entry.target.id;
    document.querySelectorAll('nav a').forEach(link => {
      link.classList.toggle('active', link.getAttribute('href') === `#${id}`);
    });
  }
}, { rootMargin: '-40% 0px -55% 0px' });

document.querySelectorAll('section[id]').forEach(s => spy.observe(s));

Ungültige Einheiten abfangen

try {
  new IntersectionObserver(() => {}, { rootMargin: '2em' });
} catch (err) {
  console.log(err.name);
}

SyntaxError

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie observer.rootMargin = '100px' hat keine Wirkung (im Strict Mode wird ein TypeError geworfen). Um den Rand zu ändern, musst du einen neuen Observer erzeugen und den alten mit disconnect() beenden.
Nur px und %: Einheiten wie em, rem oder vh sowie eine fehlende Einheit bei Werten ungleich 0 lösen im Konstruktor einen SyntaxError aus.
Cross-Origin-iframes: Wenn der implizite Root (Viewport der obersten Seite) verwendet wird und das beobachtete Element in einem iframe mit anderem Ursprung liegt, wird rootMargin aus Datenschutzgründen ignoriert.
Clipping durch Vorfahren: rootMargin erweitert nur das Rechteck des Roots. Scrollcontainer zwischen Root und Ziel mit overflow: hidden/auto schneiden weiterhin ab, sodass ein positiver Rand dort womöglich keine Wirkung zeigt. Neuere Browser bieten dafür die Option scrollMargin (noch nicht überall verfügbar).
Die Normalisierung des Rückgabewerts kann sich zwischen Browsern leicht unterscheiden. Vergleiche daher besser nicht exakt mit dem übergebenen String.
Kompatibilität: in allen modernen Browsern verfügbar (Chrome 51+, Firefox 55+, Safari 12.1+). Für sehr alte Browser gibt es ein Polyfill.

Siehe auch

IntersectionObserver.scrollMargin IntersectionObserver.root IntersectionObserver.delay IntersectionObserver.thresholds IntersectionObserver.trackVisibility