Element.scrollTop — Eigenschaft · JavaScript-Referenz

Signatur

Element.scrollTop

Beschreibung

scrollTop gibt an, wie weit der Inhalt eines scrollbaren Elements nach oben aus dem sichtbaren Bereich verschoben ist. Ist das Element ganz oben, ist der Wert 0. Wenn man die Eigenschaft beschreibt, scrollt das Element sofort an die angegebene Position.

Typische Anwendungen sind:

„Nach oben“-Buttons
Chatfenster, die automatisch ans Ende springen
Endloses Scrollen (Nachladen, wenn das Ende fast erreicht ist)
Speichern und Wiederherstellen der Scrollposition

Zusammen mit scrollHeight und clientHeight lässt sich genau berechnen, ob das Ende erreicht ist: scrollHeight - scrollTop - clientHeight ist der Rest, der noch gescrollt werden kann.

Für die ganze Seite nutzt man document.scrollingElement.scrollTop (im Standardmodus ist das document.documentElement) oder alternativ window.scrollY. Beim Setzen wird der Wert auf den gültigen Bereich von 0 bis scrollHeight - clientHeight begrenzt.

Parameter

Name	Typ	Default	Beschreibung
$wert	number		Nur beim Setzen: die gewünschte vertikale Scrollposition in CSS-Pixeln. Negative Werte werden zu `0`, zu große Werte werden auf das Maximum begrenzt.

Rückgabewert

Typ

number

Beschreibung

Die aktuelle vertikale Scrollposition in CSS-Pixeln. Auf Bildschirmen mit Skalierung kann der Wert eine Nachkommastelle haben (Subpixel). Bei Elementen, die nicht scrollen können, ist der Wert 0.

Beispiele

Chatfenster automatisch ans Ende scrollen

const chat = document.querySelector('#chat');

const addMessage = (text) => {
  // Nur mitscrollen, wenn der Nutzer schon (fast) ganz unten war
  const amEnde = chat.scrollHeight - chat.scrollTop - chat.clientHeight < 5;

  const p = document.createElement('p');
  p.textContent = text;
  chat.append(p);

  if (amEnde) {
    chat.scrollTop = chat.scrollHeight; // wird automatisch auf das Maximum begrenzt
  }
};

addMessage('Hallo!');

Endloses Scrollen: Nachladen kurz vor dem Ende

const liste = document.querySelector('.feed');
let laedt = false;

liste.addEventListener('scroll', async () => {
  const rest = liste.scrollHeight - liste.scrollTop - liste.clientHeight;
  if (rest < 200 && !laedt) {
    laedt = true;
    const res = await fetch('/api/posts?offset=' + liste.children.length);
    const posts = await res.json();
    posts.forEach(({ title }) => {
      const li = document.createElement('li');
      li.textContent = title;
      liste.append(li);
    });
    laedt = false;
  }
}, { passive: true });

Seiten-Scrollposition lesen und „Nach oben“-Button

const root = document.scrollingElement; // meist <html>
console.log('Aktuelle Position:', root.scrollTop);

document.querySelector('#nach-oben').addEventListener('click', () => {
  // Ruckartig: root.scrollTop = 0;
  // Weich animiert:
  root.scrollTo({ top: 0, behavior: 'smooth' });
});

Aktuelle Position: 0

Scrollposition speichern und wiederherstellen

const panel = document.querySelector('.sidebar');

// Position vor dem Verlassen der Seite merken
window.addEventListener('pagehide', () => {
  sessionStorage.setItem('sidebarScroll', String(panel.scrollTop));
});

// Beim Laden wiederherstellen
const gespeichert = Number(sessionStorage.getItem('sidebarScroll') ?? 0);
panel.scrollTop = gespeichert;
console.log(panel.scrollTop);

z. B. 340

// Wichtig · Fallstricke

Subpixel-Werte: Bei Zoom oder hochauflösenden Bildschirmen kann scrollTop eine Kommazahl liefern. Prüfen Sie „ganz unten“ deshalb nicht mit ===, sondern mit einem kleinen Spielraum (z. B. < 1).
Ganze Seite: Im Quirks-Modus scrollt document.body statt document.documentElement. Mit document.scrollingElement müssen Sie diesen Unterschied nicht selbst behandeln.
Nur scrollbare Elemente: Das Element braucht eine begrenzte Höhe und overflow: auto | scroll | hidden. Sonst bleibt der Wert 0 und Zuweisungen haben keine Wirkung.
Layout-Neuberechnung: Wenn Sie scrollTop lesen, nachdem Sie das DOM geändert haben, muss der Browser das Layout sofort neu berechnen (Reflow). Vermeiden Sie in Schleifen den Wechsel zwischen Lesen und Schreiben und bündeln Sie die Zugriffe, z. B. mit requestAnimationFrame.
Weiches Scrollen: Eine Zuweisung beachtet die CSS-Regel scroll-behavior: smooth. Direkt nach der Zuweisung kann der gelesene Wert daher noch der alte sein.
Scroll-Events: Das scroll-Event wird sehr oft ausgelöst. Registrieren Sie Handler mit { passive: true } und drosseln Sie sie bei Bedarf. Um Sichtbarkeit zu erkennen, ist IntersectionObserver oft die bessere Wahl.
Die Eigenschaft wird von allen Browsern unterstützt. Das behavior-Optionsobjekt von scrollTo() funktioniert in allen modernen Browsern.

Siehe auch

Element.scrollLeft Element.scrollHeight Element.clientHeight Element.scrollTo() Element.scrollIntoView() Window.scrollY Document.scrollingElement IntersectionObserver