Add opt-in scroll restoration for back/forward navigation (#577)

The browser's same-document heuristic loses the saved offset when the
destination route forces a layout while the document is short. With
<Router scrollRestoration> the router owns it: manual mode, positions
captured per history entry depth, persisted across reloads, restored
after navigation settles with a growth guard for late content.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ryansolid

.changeset/opt-in-scroll-restoration.md

@@ -0,0 +1,5 @@
+---
+"@solidjs/router": patch
+---
+
+Add opt-in explicit scroll restoration for back/forward navigation: `<Router scrollRestoration>` (#577). The browser's native same-document heuristic loses the saved offset when the destination route forces a layout while the document is still short — any component that measures itself on mount is enough to trigger it. When enabled the router sets `history.scrollRestoration = "manual"`, captures positions continuously keyed by the history entry depth it already tracks, persists them across reloads, and restores after the navigation settles — retrying as the document grows if the target offset isn't reachable yet, cancelled by the first user scroll. Off by default on 0.x; no behavior changes unless enabled.

src/routers/Router.ts

@@ -5,11 +5,26 @@ import { setupNativeEvents } from "../data/events.js";
 import type { BaseRouterProps } from "./components.jsx";
 import type { JSX } from "solid-js";
 import { createBeforeLeave, keepDepth, notifyIfNotBlocked, saveCurrentDepth } from "../lifecycle.js";
+import { createScrollRestoration } from "./scrollRestoration.js";
 
-export type RouterProps = BaseRouterProps & { url?: string, actionBase?: string, explicitLinks?: boolean, preload?: boolean };
+export type RouterProps = BaseRouterProps & {
+  url?: string,
+  actionBase?: string,
+  explicitLinks?: boolean,
+  preload?: boolean,
+  /**
+   * Opt-in explicit scroll restoration for back/forward navigation (read
+   * once, not reactive). Sets `history.scrollRestoration = "manual"` and
+   * restores saved positions after the navigation settles, replacing the
+   * browser heuristic that loses offsets when the destination route forces
+   * a layout while rendering (#577).
+   */
+  scrollRestoration?: boolean
+};
 
 export function Router(props: RouterProps): JSX.Element {
   if (isServer) return StaticRouter(props);
+  const restoration = props.scrollRestoration ? createScrollRestoration() : undefined;
   const getSource = () => {
     const url = window.location.pathname + window.location.search;
     const state = window.history.state && window.history.state._depth && Object.keys(window.history.state).length === 1 ? undefined : window.history.state;
@@ -29,18 +44,28 @@ export function Router(props: RouterProps): JSX.Element {
       }
       scrollToHash(decodeURIComponent(window.location.hash.slice(1)), scroll);
       saveCurrentDepth();
+      restoration && !replace && restoration.onPush();
     },
-    init: notify => bindEvent(window, "popstate",
-        notifyIfNotBlocked(notify, delta => {
-          if (delta) {
-            return !beforeLeave.confirm(delta);
-          } else {
-            const s = getSource();
-            return !beforeLeave.confirm(s.value, { state: s.state });
+    init: notify => {
+      const handler = notifyIfNotBlocked(notify, delta => {
+        if (delta) {
+          return !beforeLeave.confirm(delta);
+        } else {
+          const s = getSource();
+          return !beforeLeave.confirm(s.value, { state: s.state });
+        }
+      });
+      return bindEvent(window, "popstate", restoration
+        ? () => {
+            restoration.onPop();
+            handler();
           }
-        })
-      ),
-    create: setupNativeEvents({ preload: props.preload, explicitLinks: props.explicitLinks, actionBase: props.actionBase, transformUrl: props.transformUrl }),
+        : handler);
+    },
+    create: router => {
+      setupNativeEvents({ preload: props.preload, explicitLinks: props.explicitLinks, actionBase: props.actionBase, transformUrl: props.transformUrl })(router);
+      restoration && restoration.create(router);
+    },
     utils: {
       go: delta => window.history.go(delta),
       beforeLeave

src/routers/scrollRestoration.ts

@@ -0,0 +1,107 @@
+import { createEffect, on, onCleanup } from "solid-js";
+import { saveCurrentDepth } from "../lifecycle.js";
+import type { RouterContext } from "../types.js";
+import { bindEvent } from "./createRouter.js";
+
+const STORAGE_KEY = "solid-router:scroll";
+
+/**
+ * Explicit scroll restoration for back/forward navigation. The browser's
+ * native same-document heuristic is unreliable for suspense-driven rendering:
+ * if the destination route forces a layout while the document is still short,
+ * the saved offset for the previous entry is clamped and lost (#577).
+ *
+ * Positions are captured continuously from the scroll event, keyed by the
+ * `_depth` the router already stamps on every history entry — capturing at
+ * scroll time (rather than at exit) stays correct through `useBeforeLeave`
+ * blocked/reverted traversals. The map persists to sessionStorage on pagehide
+ * so restoration survives reloads, which `scrollRestoration = "manual"`
+ * otherwise disables. Restoration runs once routing settles; if the document
+ * is still shorter than the target (a boundary below the fold hasn't
+ * resolved), a ResizeObserver retries as content grows, cancelled by the
+ * first user scroll.
+ */
+export function createScrollRestoration() {
+  window.history.scrollRestoration = "manual";
+  // the current entry needs its depth stamp for captures to have a key, even
+  // if something replaced history.state after the lifecycle module loaded
+  saveCurrentDepth();
+  let positions: Record<string, number> = {};
+  try {
+    positions = JSON.parse(sessionStorage.getItem(STORAGE_KEY)!) || {};
+  } catch {}
+
+  const depth = (): number | undefined => window.history.state && window.history.state._depth;
+
+  let programmatic = false;
+  let pending: number | undefined;
+  let disconnect: (() => void) | undefined;
+  const cancelGuard = () => {
+    disconnect && disconnect();
+    disconnect = undefined;
+  };
+
+  const unbind = [
+    bindEvent(window, "scroll", () => {
+      const d = depth();
+      if (d != null) positions[d] = window.scrollY;
+      if (!programmatic) {
+        // the user took over — a pending or chasing restore would yank them
+        pending = undefined;
+        cancelGuard();
+      }
+    }),
+    bindEvent(window, "pagehide", () => {
+      try {
+        sessionStorage.setItem(STORAGE_KEY, JSON.stringify(positions));
+      } catch {}
+    })
+  ];
+
+  const restore = () => {
+    if (pending == null) return;
+    const y = positions[pending];
+    pending = undefined;
+    if (y == null) return;
+    cancelGuard();
+    const attempt = () => {
+      programmatic = true;
+      window.scrollTo(0, y);
+      programmatic = false;
+      // reachable once the document is tall enough to hold the offset
+      return document.documentElement.scrollHeight - window.innerHeight >= y;
+    };
+    if (!attempt() && typeof ResizeObserver !== "undefined") {
+      const observer = new ResizeObserver(() => attempt() && cancelGuard());
+      observer.observe(document.documentElement);
+      disconnect = () => observer.disconnect();
+    }
+  };
+
+  return {
+    /** Before the router reacts to a popstate: mark the traversal target. */
+    onPop() {
+      pending = depth();
+    },
+    /** After a push: forward entries died, and this depth may be reused. */
+    onPush() {
+      const d = depth();
+      if (d != null) for (const k in positions) +k >= d && delete positions[k];
+    },
+    create(router: RouterContext) {
+      createEffect(on(router.isRouting, routing => routing || restore(), { defer: true }));
+      onCleanup(() => {
+        unbind.forEach(u => u());
+        cancelGuard();
+      });
+      // reload/back_forward document loads land on an existing entry; a fresh
+      // navigation starts a new one and belongs at the top
+      const [nav] = (performance.getEntriesByType &&
+        performance.getEntriesByType("navigation")) as PerformanceNavigationTiming[];
+      if (nav && nav.type !== "navigate") {
+        pending = depth();
+        restore();
+      }
+    }
+  };
+}

test/scroll-restoration.spec.tsx

@@ -0,0 +1,133 @@
+import { render } from "solid-js/web";
+import { vi } from "vitest";
+import { Router, Route, useNavigate } from "../src/index.js";
+import type { Navigator } from "../src/index.js";
+
+// jsdom implements history traversal but not scrolling — stub the primitives
+// so the restoration path (capture on scroll, restore via scrollTo) is
+// observable.
+function stubScrolling() {
+  let y = 0;
+  Object.defineProperty(window, "scrollY", { configurable: true, get: () => y });
+  const scrollTo = vi.fn((_x: number, newY: number) => {
+    y = newY;
+    window.dispatchEvent(new Event("scroll"));
+  });
+  window.scrollTo = scrollTo as any;
+  return {
+    scrollTo,
+    scrollUserTo(newY: number) {
+      y = newY;
+      window.dispatchEvent(new Event("scroll"));
+    }
+  };
+}
+
+describe("scroll restoration (#577)", () => {
+  beforeEach(() => {
+    window.history.replaceState(null, "", "/");
+    sessionStorage.clear();
+  });
+
+  test("is off by default", () => {
+    window.history.scrollRestoration = "auto";
+    const dispose = render(
+      () => (
+        <Router>
+          <Route path="/" component={() => null} />
+        </Router>
+      ),
+      document.body
+    );
+    try {
+      expect(window.history.scrollRestoration).toBe("auto");
+    } finally {
+      document.body.innerHTML = "";
+      dispose();
+    }
+  });
+
+  test("restores the saved position on back navigation", async () => {
+    const scrolling = stubScrolling();
+    let navigate!: Navigator;
+
+    const Long = () => {
+      navigate = useNavigate();
+      return <div data-testid="long">long</div>;
+    };
+
+    const dispose = render(
+      () => (
+        <Router scrollRestoration>
+          <Route path="/" component={Long} />
+          <Route path="/short" component={() => <div data-testid="short">short</div>} />
+        </Router>
+      ),
+      document.body
+    );
+
+    try {
+      expect(window.history.scrollRestoration).toBe("manual");
+
+      // user scrolls down the long page, then navigates away
+      scrolling.scrollUserTo(3000);
+      navigate("/short");
+      await vi.waitFor(() => expect(document.querySelector("[data-testid=short]")).toBeTruthy());
+      // push navigations still scroll to the top
+      expect(scrolling.scrollTo).toHaveBeenLastCalledWith(0, 0);
+
+      window.history.back();
+      await vi.waitFor(() => expect(document.querySelector("[data-testid=long]")).toBeTruthy());
+      await vi.waitFor(() => expect(scrolling.scrollTo).toHaveBeenLastCalledWith(0, 3000));
+    } finally {
+      document.body.innerHTML = "";
+      dispose();
+    }
+  });
+
+  test("a push prunes saved positions for truncated forward entries", async () => {
+    const scrolling = stubScrolling();
+    let navigate!: Navigator;
+
+    const Page = () => {
+      navigate = useNavigate();
+      return <div data-testid="page">page</div>;
+    };
+
+    const dispose = render(
+      () => (
+        <Router scrollRestoration>
+          <Route path="/" component={Page} />
+          <Route path="/a" component={Page} />
+          <Route path="/b" component={Page} />
+        </Router>
+      ),
+      document.body
+    );
+
+    try {
+      navigate("/a");
+      await vi.waitFor(() => expect(window.location.pathname).toBe("/a"));
+      scrolling.scrollUserTo(500);
+
+      window.history.back();
+      await vi.waitFor(() => expect(window.location.pathname).toBe("/"));
+
+      // pushing /b truncates the forward entry (/a at the same depth) — its
+      // saved position must not leak into the fresh /b entry
+      navigate("/b");
+      await vi.waitFor(() => expect(window.location.pathname).toBe("/b"));
+      scrolling.scrollTo.mockClear();
+
+      window.history.back();
+      await vi.waitFor(() => expect(window.location.pathname).toBe("/"));
+      window.history.forward();
+      await vi.waitFor(() => expect(window.location.pathname).toBe("/b"));
+      await Promise.resolve();
+      expect(scrolling.scrollTo).not.toHaveBeenCalledWith(0, 500);
+    } finally {
+      document.body.innerHTML = "";
+      dispose();
+    }
+  });
+});