Element.scrollLeft — Eigenschaft · JavaScript-Referenz

Signatur

Element.scrollLeft

Beschreibung

scrollLeft ist eine les- und schreibbare Eigenschaft jedes Elements. Beim Lesen erhältst du die aktuelle horizontale Scroll-Position des Inhalts in CSS-Pixeln. Beim Schreiben scrollt der Browser den Inhalt sofort an diese Position. Du brauchst sie zum Beispiel für horizontale Karussells, breite Tabellen, Zeitleisten oder synchron scrollende Bereiche.

Scrollen kann ein Element nur, wenn sein Inhalt breiter ist als der sichtbare Bereich (scrollWidth > clientWidth) und overflow-x auf auto, scroll oder hidden steht. Sonst ist der Wert immer 0, und Zuweisungen haben keine Wirkung. Der größte mögliche Wert ist scrollWidth - clientWidth. Werte außerhalb von 0 bis zu diesem Maximum werden automatisch begrenzt.

Für das gesamte Dokument verwendest du document.scrollingElement.scrollLeft (im Standardmodus ist das document.documentElement) oder window.scrollX. Möchtest du weich scrollen, nutze element.scrollTo({ left, behavior: 'smooth' }) oder die CSS-Eigenschaft scroll-behavior: smooth. Diese CSS-Eigenschaft wirkt auch auf direkte Zuweisungen an scrollLeft.

Parameter

Name	Typ	Default	Beschreibung
$value	number		Nur beim Schreiben: die gewünschte horizontale Scroll-Position in Pixeln. Nachkommastellen sind erlaubt. Der Wert wird auf den gültigen Bereich begrenzt.

Rückgabewert

Typ

number

Beschreibung

Die aktuelle horizontale Scroll-Position in CSS-Pixeln. Bei hochauflösenden Bildschirmen und Zoom kann das eine Kommazahl sein. Bei Schreibrichtung von rechts nach links (direction: rtl) ist der Wert 0 oder negativ.

Beispiele

Scroll-Position auslesen und setzen

const box = document.querySelector('#tabelle-wrapper');

console.log(box.scrollLeft); // z. B. 0

// 200 px nach rechts scrollen
box.scrollLeft = 200;
console.log(box.scrollLeft); // 200 (oder weniger, falls das Maximum kleiner ist)

// Ganz ans rechte Ende scrollen
box.scrollLeft = box.scrollWidth - box.clientWidth;

0 200

Karussell mit Vor/Zurück-Buttons

const track = document.querySelector('.carousel');
const step = () => track.clientWidth * 0.8;

document.querySelector('.next').addEventListener('click', () => {
  track.scrollBy({ left: step(), behavior: 'smooth' });
});

document.querySelector('.prev').addEventListener('click', () => {
  track.scrollBy({ left: -step(), behavior: 'smooth' });
});

// Buttons am Rand deaktivieren
track.addEventListener('scroll', () => {
  const max = track.scrollWidth - track.clientWidth;
  document.querySelector('.prev').disabled = track.scrollLeft <= 0;
  document.querySelector('.next').disabled = track.scrollLeft >= max - 1;
}, { passive: true });

Kopfzeile und Tabellenkörper synchron scrollen

const header = document.querySelector('.grid-header');
const body = document.querySelector('.grid-body');

body.addEventListener('scroll', () => {
  // Kopfzeile folgt der horizontalen Position des Körpers
  header.scrollLeft = body.scrollLeft;
}, { passive: true });

Scroll-Fortschritt in Prozent berechnen

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

const progress = (el) => {
  const max = el.scrollWidth - el.clientWidth;
  return max > 0 ? Math.round((Math.abs(el.scrollLeft) / max) * 100) : 0;
};

timeline.addEventListener('scroll', () => {
  console.log(`Fortschritt: ${progress(timeline)} %`);
});

Fortschritt: 42 %

// Wichtig · Fallstricke

Schreibrichtung von rechts nach links: Bei direction: rtl ist die Startposition laut Spezifikation 0, und beim Scrollen nach links werden die Werte negativ. Chrome hält sich seit Version 85 daran, Firefox und Safari schon länger. Ältere Chromium-Versionen lieferten positive Werte. Rechne deshalb mit Math.abs(), wenn du beide Fälle abdecken musst.
Kommazahlen: Bei Zoom oder hochauflösenden Bildschirmen kann scrollLeft Nachkommastellen haben. Wenn du prüfst, ob das Ende erreicht ist, vergleiche mit etwas Spielraum (z. B. >= max - 1) statt mit exakter Gleichheit.
Performance: Wer scrollLeft liest, zwingt den Browser zu einer sofortigen Layout-Berechnung (Reflow). Wechselst du in Schleifen zwischen Lesen und Schreiben von Layout-Werten, wird die Seite langsam. Fasse Lesezugriffe zusammen und schreibe in requestAnimationFrame. Registriere Scroll-Listener mit { passive: true }.
Keine Wirkung: Die Zuweisung hat keinen Effekt, wenn das Element nicht scrollbar ist (overflow: visible, kein überstehender Inhalt) oder mit display: none nicht dargestellt wird.
Dokument scrollen: Für die ganze Seite verwendest du document.scrollingElement. Im Quirks-Modus ist das document.body, im Standardmodus document.documentElement.
Weiches Scrollen: Mit scroll-behavior: smooth scrollt auch eine direkte Zuweisung weich. Ein sofortiges Zurücklesen liefert dann noch den alten oder einen Zwischenwert.

Siehe auch

Element.scrollTop Element.scrollWidth Element.clientWidth Element.scrollTo() Element.scrollBy() Element.scrollIntoView() Window.scrollX