IntersectionObserver.scrollMargin — Eigenschaft · JavaScript-Referenz

Signatur

IntersectionObserver.scrollMargin

Beschreibung

Die Eigenschaft scrollMargin eines IntersectionObserver gibt den Rand zurück, der bei der Schnittberechnung auf alle verschachtelten Scroll-Container zwischen Ziel und Root angewendet wird. Ist das Root-Element selbst ein Scroll-Container, gilt der Rand auch dort. Obwohl die MDN-Kurzbeschreibung von einer „Schreibeigenschaft“ spricht, ist die Eigenschaft nur lesbar: Gesetzt wird der Wert ausschließlich über die Option scrollMargin im Konstruktor new IntersectionObserver(callback, options).

Warum braucht man das? rootMargin erweitert nur das Rechteck des Roots. Liegt ein Ziel aber in einem verschachtelten Scroll-Container, etwa in einem horizontalen Karussell mit overflow: auto, schneidet dieser Container das Ziel vorher ab. Elemente, die knapp außerhalb des sichtbaren Karussellbereichs liegen, gelten dann trotz großzügigem rootMargin als „nicht sichtbar“. Mit scrollMargin wird das Clipping-Rechteck jedes solchen Containers erweitert. So kann man z. B. Bilder in Karussells rechtzeitig per Lazy Loading nachladen, bevor der Nutzer dorthin scrollt.

Der zurückgegebene Wert ist ein normalisierter String mit vier Werten in CSS-Reihenfolge (oben, rechts, unten, links), z. B. "0px 200px 0px 200px". Wurde im Konstruktor nichts angegeben, lautet er "0px 0px 0px 0px". Erlaubt sind Längen in px und Prozentwerte, positiv (erweitern) wie negativ (verkleinern).

Parameter

Name	Typ	Default	Beschreibung
$options.scrollMargin	string	"0px 0px 0px 0px"	Wird im Konstruktor übergeben (nicht an der Eigenschaft). Ein bis vier Werte im Stil der CSS-Eigenschaft `margin`, nur in `px` oder `%`, z. B. `"50px"` oder `"0px 20%"`. Ungültige Einheiten wie `em` lösen einen `SyntaxError` aus.

Rückgabewert

Typ

string

Beschreibung

Der normalisierte Rand mit immer vier Werten, z. B. "10px 10px 10px 10px". In Browsern ohne Unterstützung ist der Wert undefined.

Beispiele

Lazy Loading in einem horizontalen Karussell

// HTML: <div class="carousel" style="overflow-x: auto; display: flex">
//         <img data-src="bild1.jpg"> ... </div>
const observer = new IntersectionObserver((entries, obs) => {
  for (const entry of entries) {
    if (!entry.isIntersecting) continue;
    const img = entry.target;
    img.src = img.dataset.src; // Bild nachladen
    obs.unobserve(img);
  }
}, {
  rootMargin: '200px 0px',     // Viewport nach oben/unten erweitern
  scrollMargin: '0px 300px'    // Karussell nach links/rechts erweitern
});

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

console.log(observer.scrollMargin);

0px 300px 0px 300px

Standardwert und Normalisierung auslesen

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

const eigener = new IntersectionObserver(() => {}, { scrollMargin: '10px 5%' });
console.log(eigener.scrollMargin);

// Nur lesbar: Zuweisung wird ignoriert (im strict mode TypeError)
try {
  'use strict';
  eigener.scrollMargin = '50px';
} catch (e) {
  console.log(e.name);
}
console.log(eigener.scrollMargin);

0px 0px 0px 0px 10px 5% 10px 5% 10px 5% 10px 5%

Feature-Erkennung mit Fallback

const unterstuetztScrollMargin = () =>
  'IntersectionObserver' in window &&
  'scrollMargin' in IntersectionObserver.prototype;

const erstelleObserver = (callback) => {
  if (unterstuetztScrollMargin()) {
    return new IntersectionObserver(callback, { scrollMargin: '0px 400px' });
  }
  // Fallback: Container selbst als Root verwenden
  return new IntersectionObserver(callback, {
    root: document.querySelector('.carousel'),
    rootMargin: '0px 400px'
  });
};

const obs = erstelleObserver((entries) => console.log(entries.length));
console.log(unterstuetztScrollMargin());

true (in Chromium 120+), sonst false

// Wichtig · Fallstricke

Nur lesbar: Um den Wert zu ändern, muss ein neuer Observer mit anderer scrollMargin-Option erstellt werden. Der alte Observer sollte vorher mit disconnect() getrennt werden.
Browser-Kompatibilität: Unterstützt ab Chrome/Edge 120. Firefox und Safari unterstützen die Eigenschaft bislang nicht oder nur in neuesten Versionen. Unbekannte Optionen werden dort stillschweigend ignoriert. Deshalb eine Feature-Erkennung verwenden ('scrollMargin' in IntersectionObserver.prototype).
Abgrenzung zu rootMargin: rootMargin wirkt nur auf das Root-Rechteck (bei root: null also den Viewport), scrollMargin dagegen auf jeden verschachtelten Scroll-Container. Beide lassen sich kombinieren.
Nur px und % sind erlaubt. Andere Einheiten führen im Konstruktor zu einem SyntaxError.
Nicht zu verwechseln mit der CSS-Eigenschaft scroll-margin, die das Einrasten beim Scroll-Snapping und bei scrollIntoView() steuert.

Siehe auch

IntersectionObserver.root IntersectionObserver.rootMargin IntersectionObserver.delay IntersectionObserver.thresholds IntersectionObserver.trackVisibility