History.scrollRestoration — Eigenschaft · JavaScript-Referenz

Signatur

History.scrollRestoration

Beschreibung

Die Eigenschaft history.scrollRestoration legt fest, wie sich der Browser bei der Verlaufsnavigation verhält, also beim Zurück- oder Vorwärtsgehen und bei history.back(), history.forward() oder history.go(). Standardmäßig steht sie auf "auto": Der Browser merkt sich die Scrollposition eines Verlaufseintrags und stellt sie bei der Rückkehr wieder her.

Mit "manual" schaltet man diese Automatik ab. Das ist vor allem in Single-Page-Applications sinnvoll, die ihre Inhalte über history.pushState() und das popstate-Ereignis selbst rendern. Dort springt die automatische Wiederherstellung oft an die falsche Stelle, weil der Inhalt beim Zurücknavigieren noch gar nicht geladen ist. Die App speichert die Position dann selbst, etwa im state-Objekt oder im sessionStorage, und scrollt erst nach dem Rendern gezielt dorthin.

Die Einstellung gilt pro Verlaufseintrag. Wer "manual" setzt und danach mit pushState() neue Einträge anlegt, übernimmt den Wert für diese Einträge. Es ist trotzdem üblich, die Eigenschaft einmal beim Start der Anwendung zu setzen.

Parameter

Name	Typ	Default	Beschreibung
$value	"auto" \| "manual"	"auto"	Nur beim Schreiben: `"auto"` stellt die Scrollposition automatisch wieder her, `"manual"` überlässt das der Anwendung. Ungültige Werte werden stillschweigend ignoriert.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Modus des Verlaufseintrags: "auto" oder "manual".

Beispiele

Aktuellen Wert auslesen und mit Feature-Erkennung umschalten

console.log(history.scrollRestoration);

if ('scrollRestoration' in history) {
  history.scrollRestoration = 'manual';
}

console.log(history.scrollRestoration);

auto manual

SPA: Scrollposition selbst speichern und nach dem Rendern wiederherstellen

history.scrollRestoration = 'manual';

const render = async (path) => {
  const main = document.querySelector('main');
  const res = await fetch(`/partials${path}.html`);
  main.innerHTML = await res.text();
};

const navigate = async (path) => {
  // Position des aktuellen Eintrags sichern, bevor wir weiternavigieren
  history.replaceState({ ...history.state, scrollY: window.scrollY }, '');
  history.pushState({ scrollY: 0 }, '', path);
  await render(path);
  window.scrollTo(0, 0);
};

window.addEventListener('popstate', async (event) => {
  await render(location.pathname);
  // Erst scrollen, wenn der Inhalt im DOM steht
  window.scrollTo(0, event.state?.scrollY ?? 0);
});

document.addEventListener('click', (e) => {
  const link = e.target.closest('a[data-spa]');
  if (!link) return;
  e.preventDefault();
  navigate(new URL(link.href).pathname);
});

Beim Zurücknavigieren immer oben beginnen

// z. B. für ein Bildschirm-für-Bildschirm-Formular, bei dem ein Sprung in die Mitte stören würde
history.scrollRestoration = 'manual';

window.addEventListener('popstate', () => {
  window.scrollTo({ top: 0, behavior: 'instant' });
});

// Wichtig · Fallstricke

Kompatibilität: Wird von allen modernen Browsern unterstützt, vom Internet Explorer nicht. Vor dem Setzen sollte man mit 'scrollRestoration' in history prüfen, ob die Eigenschaft vorhanden ist.
Pro Verlaufseintrag: Der Wert hängt am jeweiligen Eintrag. Ein Seiten-Reload oder eine Navigation zu einem ganz neuen Dokument setzt ihn wieder auf "auto". Deshalb muss man ihn bei jedem Laden der Seite erneut setzen.
Ungültige Werte wie 'none' werden ohne Fehlermeldung ignoriert, der bisherige Wert bleibt bestehen.
Bei "manual" ist die Anwendung vollständig selbst für die Scrollposition verantwortlich. Wer das vergisst, landet beim Zurücknavigieren an einer zufälligen Stelle oder ganz oben.
Der Back-Forward-Cache (bfcache) stellt Seiten samt Scrollposition wieder her. Dabei wird das Ereignis pageshow mit event.persisted === true ausgelöst, nicht popstate.
Sprungmarken wie #abschnitt werden von der Einstellung nicht berührt, beim Laden scrollt der Browser weiterhin dorthin.

Siehe auch

History History.pushState() History.replaceState() History.state Window.scrollTo() PerformanceServerTiming.duration