Document.scrollingElement — Eigenschaft · JavaScript-Referenz

Signatur

get Document.scrollingElement

Beschreibung

Die schreibgeschützte Eigenschaft document.scrollingElement gibt eine Referenz auf das Element zurück, das für das Scrollen des gesamten Dokuments (des Viewports) zuständig ist. Im Standardmodus (<!DOCTYPE html>) ist das document.documentElement, also <html>. Im Quirks-Modus ist es document.body, sofern dieses Element selbst nicht scrollbar ist.

Früher mussten Entwickler raten, ob document.documentElement.scrollTop oder document.body.scrollTop den richtigen Wert liefert – das hing von Browser und Rendermodus ab. scrollingElement beseitigt dieses Problem: Man liest oder setzt scrollTop, scrollLeft, scrollHeight usw. direkt am zurückgegebenen Element und muss sich nicht um die Unterschiede kümmern.

Typische Einsatzfälle sind Scroll-Fortschrittsanzeigen, „Nach oben“-Schaltflächen, das Speichern und Wiederherstellen der Scrollposition sowie Bibliotheken, die sowohl in Standard- als auch in Quirks-Dokumenten zuverlässig funktionieren müssen.

Rückgabewert

Typ

Element | null

Beschreibung

Das Element, das das Dokument scrollt – normalerweise document.documentElement, im Quirks-Modus ggf. document.body. null, wenn kein solches Element existiert (z. B. im Quirks-Modus ohne <body> oder wenn <body> selbst scrollbar ist).

Beispiele

Scrolling-Element ermitteln

const scroller = document.scrollingElement;
console.log(scroller.tagName);
console.log(document.compatMode);

HTML CSS1Compat

Scroll-Fortschrittsbalken

const bar = document.querySelector('#progress');

const updateProgress = () => {
  const el = document.scrollingElement ?? document.documentElement;
  const max = el.scrollHeight - el.clientHeight;
  const percent = max > 0 ? (el.scrollTop / max) * 100 : 0;
  bar.style.width = `${percent.toFixed(1)}%`;
};

window.addEventListener('scroll', updateProgress, { passive: true });
updateProgress();

„Nach oben“-Button und Position merken

const scroller = document.scrollingElement;

// Position beim Verlassen speichern
window.addEventListener('pagehide', () => {
  sessionStorage.setItem('scrollY', String(scroller.scrollTop));
});

// Position beim Laden wiederherstellen
const saved = Number(sessionStorage.getItem('scrollY') ?? 0);
scroller.scrollTop = saved;

// Sanft nach oben scrollen
document.querySelector('#to-top').addEventListener('click', () => {
  scroller.scrollTo({ top: 0, behavior: 'smooth' });
});

// Wichtig · Fallstricke

Die Eigenschaft ist schreibgeschützt – das Element selbst lässt sich nicht austauschen, seine Scroll-Eigenschaften (scrollTop, scrollLeft) aber schon.
Der Rückgabewert kann null sein; defensiver Code nutzt document.scrollingElement ?? document.documentElement.
Für reine Lesezugriffe auf die Viewport-Position sind window.scrollY/window.scrollX oft einfacher; scrollingElement ist nützlich, wenn man ein echtes Element braucht (z. B. für scrollHeight oder generische Scroll-Funktionen, die ein Element erwarten).
Der scroll-Event des Dokuments wird an window/document ausgelöst, nicht am scrollingElement selbst.
Kompatibilität: in allen modernen Browsern verfügbar; der Internet Explorer unterstützt die Eigenschaft nicht (dort ggf. Polyfill oder Fallback auf document.documentElement/document.body).

Siehe auch

Document.documentElement Document.body Element.scrollTop Element.scrollTo() Window.scrollY Document.compatMode PushSubscription.endpoint