Element.scrollTopMax — Eigenschaft · JavaScript-Referenz

Signatur

Element.scrollTopMax

Beschreibung

Die schreibgeschützte Eigenschaft Element.scrollTopMax gibt eine Zahl zurück, die den größtmöglichen oberen Scrollversatz des Elements angibt. Das ist der Wert, den scrollTop hat, wenn der Inhalt ganz nach unten gescrollt ist. Kann das Element nicht vertikal scrollen, ist der Wert 0.

Inhaltlich entspricht der Wert der Berechnung element.scrollHeight - element.clientHeight. Man braucht ihn zum Beispiel, um zu prüfen, ob ein Nutzer das Ende einer Liste erreicht hat (Endlos-Scrollen, „Nutzungsbedingungen gelesen“), um einen Scroll-Fortschritt in Prozent anzuzeigen oder um Chat-Fenster ganz nach unten zu scrollen.

Wichtig: scrollTopMax ist eine nicht standardisierte Erweiterung von Mozilla und gibt es nur in Firefox. In Chrome, Edge und Safari ist die Eigenschaft undefined. Für Code, der in allen Browsern laufen soll, nutzt man die Berechnung aus scrollHeight und clientHeight. scrollTopMax dient dann höchstens als Kurzschreibweise, wenn sie vorhanden ist.

Rückgabewert

Typ

number

Beschreibung

Maximaler vertikaler Scrollversatz in CSS-Pixeln, als Ganzzahl. 0, wenn das Element nicht vertikal scrollbar ist. In anderen Browsern als Firefox ist die Eigenschaft undefined.

Beispiele

Maximalen Scrollversatz browserübergreifend ermitteln

// Nutzt scrollTopMax, wenn vorhanden, sonst die Standard-Berechnung
const getScrollTopMax = (el) =>
  typeof el.scrollTopMax === 'number'
    ? el.scrollTopMax
    : Math.max(0, el.scrollHeight - el.clientHeight);

const box = document.querySelector('#log');
console.log(`Max. scrollTop: ${getScrollTopMax(box)}px`);

Max. scrollTop: 740px

Erkennen, ob das Ende eines Containers erreicht ist

const terms = document.querySelector('#terms');
const acceptBtn = document.querySelector('#accept');

const maxTop = (el) => el.scrollTopMax ?? (el.scrollHeight - el.clientHeight);

terms.addEventListener('scroll', () => {
  // Toleranz von 1px wegen Subpixel-Rundung bei Zoom
  if (terms.scrollTop >= maxTop(terms) - 1) {
    acceptBtn.disabled = false;
    console.log('Ende erreicht – Button freigeschaltet');
  }
}, { passive: true });

Ende erreicht – Button freigeschaltet

Scroll-Fortschritt in Prozent anzeigen

const article = document.querySelector('.article-body');
const bar = document.querySelector('.progress');

article.addEventListener('scroll', () => {
  const max = article.scrollTopMax ?? (article.scrollHeight - article.clientHeight);
  const percent = max > 0 ? Math.round((article.scrollTop / max) * 100) : 100;
  bar.style.width = `${percent}%`;
  console.log(`Gelesen: ${percent}%`);
});

Gelesen: 42%

Chat-Fenster ans Ende scrollen

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

const scrollToBottom = () => {
  const max = chat.scrollTopMax ?? (chat.scrollHeight - chat.clientHeight);
  chat.scrollTo({ top: max, behavior: 'smooth' });
};

const msg = document.createElement('p');
msg.textContent = 'Neue Nachricht';
chat.append(msg);
scrollToBottom();

// Wichtig · Fallstricke

Nicht standardisiert: Die Eigenschaft gibt es nur in Firefox, in Chromium-Browsern und Safari ist sie undefined. Sie ist in keiner Spezifikation enthalten. Verwende immer einen Rückfall über scrollHeight - clientHeight.
Nur lesbar: Wenn du der Eigenschaft einen Wert zuweist, passiert nichts. Scrollen musst du über scrollTop, scrollTo() oder scrollIntoView().
Rundung: Der Wert ist ganzzahlig. scrollTop kann bei Zoom oder hoher Pixeldichte dagegen Nachkommastellen haben. Vergleiche deshalb mit einer kleinen Toleranz (z. B. >= max - 1), statt auf exakte Gleichheit zu prüfen.
Layout-Neuberechnung: Wenn du den Wert liest, muss der Browser unter Umständen das Layout neu berechnen. In scroll-Handlern solltest du den Wert deshalb nicht bei jedem Ereignis zusammen mit DOM-Änderungen abfragen. Alternativ kannst du einen IntersectionObserver auf ein Element am Ende des Inhalts setzen.
Für das Dokument selbst liest man den Wert an document.scrollingElement (meist <html>) ab.

Siehe auch

Element.scrollTop Element.scrollLeftMax Element.scrollHeight Element.clientHeight Element.scrollTo() ElementInternals.ariaRowSpan