Window.scrollBy() — Methode · JavaScript-Referenz

Signatur

Window.prototype.scrollBy(x, y) | Window.prototype.scrollBy(options)

Beschreibung

window.scrollBy() verschiebt den sichtbaren Ausschnitt des Dokuments um einen relativen Betrag. Anders als bei window.scrollTo(), das zu einer absoluten Position springt, addiert scrollBy() die übergebenen Werte zur aktuellen Scrollposition (window.scrollX/window.scrollY). Positive Werte scrollen nach rechts bzw. unten, negative nach links bzw. oben.

Es gibt zwei Aufrufformen: die klassische mit zwei Zahlen scrollBy(x, y) und die moderne mit einem Options-Objekt scrollBy({ top, left, behavior }). Nur die Objektform erlaubt über behavior: "smooth" ein animiertes Scrollen – ideal für „Seite weiter“-Buttons, Tastatursteuerung oder Karussells.

Typische Einsatzfälle sind seitenweises Blättern (z. B. um window.innerHeight), das Ausgleichen einer fixierten Kopfzeile nach einem Sprung zu einem Anker oder schrittweises Scrollen in Präsentationen. Für einzelne scrollbare Container gibt es die gleichnamige Methode Element.scrollBy().

Parameter

Name	Typ	Default	Beschreibung
$x	number	0	Horizontaler Versatz in Pixeln (klassische Form). Positiv = nach rechts, negativ = nach links.
$y	number	0	Vertikaler Versatz in Pixeln (klassische Form). Positiv = nach unten, negativ = nach oben.
$options	ScrollToOptions	{}	Objekt mit `top` (vertikaler Versatz), `left` (horizontaler Versatz) und `behavior`: `"auto"` (Standard, folgt CSS `scroll-behavior`), `"instant"` oder `"smooth"`.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück. Auch bei behavior: "smooth" wird kein Promise geliefert – das Ende der Animation lässt sich über das Event scrollend erkennen.

Beispiele

Einfach: 100 Pixel nach unten scrollen

// Klassische Form mit zwei Zahlen
window.scrollBy(0, 100);
console.log(window.scrollY); // bei Start ganz oben und genug Inhalt

100

Seitenweise blättern mit weicher Animation

const nextBtn = document.querySelector('#weiter');
const prevBtn = document.querySelector('#zurueck');

// 90 % der Fensterhöhe, damit etwas Kontext sichtbar bleibt
const pageStep = () => Math.round(window.innerHeight * 0.9);

nextBtn.addEventListener('click', () => {
  window.scrollBy({ top: pageStep(), behavior: 'smooth' });
});

prevBtn.addEventListener('click', () => {
  window.scrollBy({ top: -pageStep(), behavior: 'smooth' });
});

Fixierte Kopfzeile nach Ankersprung ausgleichen

const header = document.querySelector('header');

const jumpTo = (id) => {
  document.getElementById(id)?.scrollIntoView();
  // Um Kopfzeilenhöhe zurückscrollen, damit die Überschrift nicht verdeckt ist
  window.scrollBy({ top: -header.offsetHeight, behavior: 'instant' });
};

jumpTo('kapitel-3');

Auf das Ende einer weichen Scrollbewegung warten

const scrollByAsync = (top) => new Promise((resolve) => {
  window.addEventListener('scrollend', resolve, { once: true });
  window.scrollBy({ top, behavior: 'smooth' });
});

await scrollByAsync(500);
console.log('Scrollen beendet bei', window.scrollY);

Scrollen beendet bei 500

// Wichtig · Fallstricke

Relativ statt absolut: Wiederholte Aufrufe summieren sich. Für feste Zielpositionen window.scrollTo() verwenden.
Keine Wirkung ohne Scrollbereich: Ist die Seite nicht höher/breiter als der Viewport oder hat html/body overflow: hidden, passiert nichts. Werte über das Ende hinaus werden stillschweigend begrenzt – es gibt keinen Fehler.
Weiches Scrollen: behavior: "smooth" funktioniert nur in der Objektform. Die Einstellung prefers-reduced-motion des Nutzers sollte respektiert werden. Schnelle Folgeaufrufe während einer laufenden Animation können sich je nach Browser gegenseitig abbrechen.
Das Ende der Animation erkennen: Einen Rückgabewert gibt es nicht. Das Event scrollend ist in Chrome/Edge 114+ und Firefox 109+ verfügbar, in Safari erst ab 26 – sonst mit scroll-Events und Timeout nachbilden.
Kompatibilität: Die Form mit zwei Zahlen funktioniert überall. Die Objektform und behavior werden von allen aktuellen Browsern unterstützt (Safari ab 14), aber nicht vom Internet Explorer.
Bruchteile von Pixeln werden je nach Browser und Zoomstufe gerundet.

Siehe auch

Window.scrollTo() Window.scroll() Element.scrollBy() Element.scrollIntoView() Window.scrollY Window.scrollX