add scrollTo prop to <ScrollRestoration/> for custom scrolling behaviour

Author: herrwitzi

.changeset/moody-hats-tickle.md

@@ -0,0 +1,5 @@
+---
+"react-router": minor
+---
+
+add scrollTo prop to <ScrollRestoration/> for custom scrolling behaviour

contributors.yml

@@ -141,6 +141,7 @@
 - HelpMe-Pls
 - HenriqueLimas
 - hernanif1
+- herrwitzi
 - hi-ogawa
 - HK-SHAO
 - holynewbie

docs/api/components/ScrollRestoration.md

@@ -87,3 +87,25 @@ element
 The key to use for storing scroll positions in [`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage).
 Defaults to `"react-router-scroll-positions"`.
 
+### scrollTo
+
+A function that will be called to scroll to a specific position.
+This is useful for custom scroll restoration logic, such as explicitly seting the scroll behaviour to "auto"
+so that CSS (scroll-behavior: smooth on the html tag) does not affect the call (the current behaviour jumps around
+when switching pages in a non-intuitive way).
+Defaults to `window.scrollTo(0, y)`.
+
+```css
+html {
+  scroll-behavior: smooth;
+}
+```
+```tsx
+<ScrollRestoration
+  scrollTo={(y) => {
+    document.documentElement.style.scrollBehavior = "auto"
+    window.scrollTo(0, y)
+    document.documentElement.style.scrollBehavior = ""
+  }}
+/>
+```

packages/react-router/__tests__/dom/scroll-restoration-test.tsx

@@ -319,6 +319,69 @@ describe(`ScrollRestoration`, () => {
       // Ensure that scroll position is restored
       expect(scrollToMock).toHaveBeenCalledWith(0, 20);
     });
+
+    it("should restore scroll position with custom scrollTo", () => {
+      let scrollToMock = jest.spyOn(window, "scrollTo");
+      let router = createMemoryRouter([
+        {
+          id: "root",
+          path: "/",
+          element: (
+            <>
+              <Outlet />
+              <ScrollRestoration
+                scrollTo={(y) => window.scrollTo(0, y)}
+              />
+              <Scripts />
+            </>
+          ),
+        },
+      ]);
+      router.state.restoreScrollPosition = 20;
+      render(
+        <FrameworkContext.Provider value={context}>
+          <RouterProvider router={router} />
+        </FrameworkContext.Provider>,
+      );
+
+      expect(scrollToMock).toHaveBeenCalledWith(0, 20);
+    });
+
+    it("should restore scroll position on navigation with custom scrollTo", () => {
+      let scrollToMock = jest.spyOn(window, "scrollTo");
+      let router = createMemoryRouter([
+        {
+          id: "root",
+          path: "/",
+          element: (
+            <>
+              <Outlet />
+              <ScrollRestoration
+                scrollTo={(y) => window.scrollTo(0, y)}
+              />
+              <Scripts />
+            </>
+          ),
+        },
+      ]);
+      render(
+        <FrameworkContext.Provider value={context}>
+          <RouterProvider router={router} />
+        </FrameworkContext.Provider>,
+      );
+      // Always called when using <ScrollRestoration />
+      expect(scrollToMock).toHaveBeenCalledWith(0, 0);
+      // Mock user scroll
+      window.scrollTo(0, 20);
+      // Mock navigation
+      redirect("/otherplace");
+      // Mock return to original page where navigation had happened
+      expect(scrollToMock).toHaveBeenCalledWith(0, 0);
+      // Mock return to original page where navigation had happened
+      redirect("/");
+      // Ensure that scroll position is restored
+      expect(scrollToMock).toHaveBeenCalledWith(0, 20);
+    });
   });
 });
 

packages/react-router/lib/dom/lib.tsx

@@ -24,6 +24,7 @@ import type {
   RelativeRoutingType,
   Router as DataRouter,
   RouterInit,
+  ScrollToFunction,
 } from "../router/router";
 import { IDLE_FETCHER, createRouter } from "../router/router";
 import type {
@@ -1934,6 +1935,11 @@ export type ScrollRestorationProps = ScriptsProps & {
    * Defaults to `"react-router-scroll-positions"`.
    */
   storageKey?: string;
+  /**
+   * A function that will be called to scroll to a specific position. Defaults to
+   * `window.scrollTo(0, y)`. This is useful for custom scroll restoration.
+   */
+  scrollTo?: ScrollToFunction;
 };
 
 /**
@@ -1968,19 +1974,21 @@ export type ScrollRestorationProps = ScriptsProps & {
  * @param {ScrollRestorationProps.getKey} props.getKey n/a
  * @param {ScriptsProps.nonce} props.nonce n/a
  * @param {ScrollRestorationProps.storageKey} props.storageKey n/a
+ * @param {ScrollRestorationProps.scrollTo} props.scrollTo n/a
  * @returns A [`<script>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script)
  * tag that restores scroll positions on navigation.
  */
 export function ScrollRestoration({
   getKey,
   storageKey,
+  scrollTo,
   ...props
 }: ScrollRestorationProps) {
   let remixContext = React.useContext(FrameworkContext);
   let { basename } = React.useContext(NavigationContext);
   let location = useLocation();
   let matches = useMatches();
-  useScrollRestoration({ getKey, storageKey });
+  useScrollRestoration({ getKey, storageKey, scrollTo });
 
   // In order to support `getKey`, we need to compute a "key" here so we can
   // hydrate that up so that SSR scroll restoration isn't waiting on React to
@@ -2019,7 +2027,7 @@ export function ScrollRestoration({
       let positions = JSON.parse(sessionStorage.getItem(storageKey) || "{}");
       let storedY = positions[restoreKey || window.history.state.key];
       if (typeof storedY === "number") {
-        window.scrollTo(0, storedY);
+        scrollTo ? scrollTo(storedY) : window.scrollTo(0, storedY);
       }
     } catch (error: unknown) {
       console.error(error);
@@ -2911,14 +2919,19 @@ function getScrollRestorationKey(
  * to `location.key`.
  * @param options.storageKey The key to use for storing scroll positions in
  * `sessionStorage`. Defaults to `"react-router-scroll-positions"`.
+ * @param options.scrollTo A function that will be called to scroll to a
+ * specific position. Defaults to `window.scrollTo(0, y)`. This is useful for custom
+ * scroll restoration.
  * @returns {void}
  */
 export function useScrollRestoration({
   getKey,
   storageKey,
+  scrollTo,
 }: {
   getKey?: GetScrollRestorationKeyFunction;
   storageKey?: string;
+  scrollTo?: ScrollToFunction;
 } = {}): void {
   let { router } = useDataRouterContext(DataRouterHook.UseScrollRestoration);
   let { restoreScrollPosition, preventScrollReset } = useDataRouterState(
@@ -2999,7 +3012,7 @@ export function useScrollRestoration({
 
       // been here before, scroll to it
       if (typeof restoreScrollPosition === "number") {
-        window.scrollTo(0, restoreScrollPosition);
+        scrollTo ? scrollTo(restoreScrollPosition) : window.scrollTo(0, restoreScrollPosition);
         return;
       }
 
@@ -3029,7 +3042,7 @@ export function useScrollRestoration({
       }
 
       // otherwise go to the top on new locations
-      window.scrollTo(0, 0);
+      scrollTo ? scrollTo(0) : window.scrollTo(0, 0);
     }, [location, restoreScrollPosition, preventScrollReset]);
   }
 }

packages/react-router/lib/router/router.ts

@@ -485,6 +485,13 @@ export interface GetScrollPositionFunction {
   (): number;
 }
 
+/**
+ * Function signature for scrolling to a specific position
+ */
+export interface ScrollToFunction {
+  (y: number): void;
+}
+
 /**
  * - "route": relative to the route hierarchy so `..` means remove all segments
  * of the current route even if it has many. For example, a `route("posts/:id")`