Element.scrollTo() — Methode · JavaScript-Referenz

Signatur

Element.prototype.scrollTo(x, y) | Element.prototype.scrollTo(options)

Beschreibung

Element.scrollTo() setzt die Scroll-Position eines scrollbaren Elements (z. B. eines Containers mit overflow: auto) auf absolute Koordinaten. Die Werte beziehen sich auf die linke obere Ecke des Inhalts, entsprechen also direkt den Eigenschaften scrollLeft und scrollTop.

Es gibt zwei Aufrufformen: mit zwei Zahlen scrollTo(x, y) oder mit einem Options-Objekt scrollTo({ top, left, behavior }). Nur die Objektform erlaubt über behavior: "smooth" ein animiertes Scrollen und das Weglassen einer Achse. Fehlt top oder left, bleibt die jeweilige Achse unverändert.

Typische Einsatzfälle sind „Nach oben“-Buttons in Seitenleisten, Chat-Fenster, die automatisch ans Ende springen, oder das Wiederherstellen einer gespeicherten Scroll-Position. Wer relativ zur aktuellen Position scrollen will, nimmt scrollBy(). Soll ein bestimmtes Kind-Element sichtbar werden, ist scrollIntoView() meist besser geeignet.

Parameter

Name	Typ	Default	Beschreibung
$x	number		Horizontale Zielposition in Pixeln (entspricht `scrollLeft`). Nur in der Zwei-Argumente-Form.
$y	number		Vertikale Zielposition in Pixeln (entspricht `scrollTop`). Nur in der Zwei-Argumente-Form.
$options	ScrollToOptions	{}	Objekt mit `top` (number), `left` (number) und `behavior`. Fehlende Koordinaten bleiben unverändert.
$options.behavior	"auto" \| "instant" \| "smooth"	"auto"	`"smooth"` animiert den Sprung, `"instant"` springt sofort, `"auto"` richtet sich nach der CSS-Eigenschaft `scroll-behavior`.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück. Die Methode liefert kein Promise, auch nicht bei weichem Scrollen – für das Ende der Animation das Event scrollend nutzen.

Beispiele

Container mit zwei Zahlen an den Anfang setzen

const liste = document.querySelector('#ergebnisliste');

// Nach einem neuen Suchergebnis sofort nach oben springen
liste.scrollTo(0, 0);
console.log(liste.scrollTop);

Chat-Fenster weich ans Ende scrollen

const chat = document.querySelector('.chat-verlauf');

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

  // Nur vertikal scrollen, left bleibt unverändert
  chat.scrollTo({ top: chat.scrollHeight, behavior: 'smooth' });
};

nachrichtHinzufuegen('Hallo zusammen!');

Scroll-Position speichern und wiederherstellen

const panel = document.querySelector('#seitenleiste');
const KEY = 'seitenleiste-scroll';

panel.addEventListener('scrollend', () => {
  sessionStorage.setItem(KEY, String(panel.scrollTop));
});

const gespeichert = Number(sessionStorage.getItem(KEY) ?? 0);
panel.scrollTo({ top: gespeichert, behavior: 'instant' });

Auf das Ende einer weichen Animation warten

const scrollToAsync = (el, options) =>
  new Promise((resolve) => {
    el.addEventListener('scrollend', resolve, { once: true });
    el.scrollTo({ ...options, behavior: 'smooth' });
  });

const galerie = document.querySelector('.galerie');
await scrollToAsync(galerie, { left: 600 });
console.log('Animation fertig bei', galerie.scrollLeft);

Animation fertig bei 600

// Wichtig · Fallstricke

Nur bei scrollbaren Elementen wirksam: Hat das Element kein overflow: auto/scroll oder ist der Inhalt nicht größer als der Container, passiert nichts – ohne Fehlermeldung.
Werte werden begrenzt: Zu große oder negative Koordinaten werden auf den gültigen Bereich (0 bis scrollHeight - clientHeight) beschnitten.
Kein Promise: Bei behavior: "smooth" kehrt der Aufruf sofort zurück; scrollTop hat dann noch den alten Wert. Für das Ende der Animation gibt es das Event scrollend (Safari erst ab Version 26 – bei älteren Versionen auf scroll plus Timeout ausweichen).
Schreibrichtung: Bei direction: rtl sind horizontale Werte in modernen Browsern 0 oder negativ.
Barrierefreiheit: Nutzer mit prefers-reduced-motion: reduce sollten kein weiches Scrollen bekommen – vorher per matchMedia() prüfen.
Kompatibilität: Die Zwei-Zahlen-Form geht überall; das Options-Objekt mit behavior fehlte in Safari bis Version 14 (dort wurde smooth ignoriert). Internet Explorer kennt Element.scrollTo() nicht; dort scrollTop/scrollLeft direkt setzen.
Die Methode hat den Alias Element.scroll(), der sich genauso verhält.

Siehe auch

Element.scroll() Element.scrollBy() Element.scrollIntoView() Element.scrollTop Element.scrollLeft Window.scrollTo()