<ScrollRestoration> with scrolling container other than window

[david-crespo]

I briefly discussed this with @brophdawg11 on Discord and he suggested starting a discussion here. He raised some useful concerns:

I'm sure the component could be altered to support a more advanced nested scroll use-case, but it introduces edge cases that would need to be thought through. Like what if when you come back to that location the scrollElement is no longer present for some reason? falling back on window isn't going to be right since the scroll position is relative to the no-longer-rendered element etc.

The problem

If you use CSS grid to define a layout where only one pane scrolls rather than the entire page, <ScrollRestoration> does not work because it only uses window.scrollY and window.scrollTo(_, _).

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

Lines 1018 to 1110 in 5f3cfb7

	function useScrollRestoration({
	getKey,
	storageKey,
	}: {
	getKey?: GetScrollRestorationKeyFunction;
	storageKey?: string;
	} = {}) {
	let { router } = useDataRouterContext(DataRouterHook.UseScrollRestoration);
	let { restoreScrollPosition, preventScrollReset } = useDataRouterState(
	DataRouterStateHook.UseScrollRestoration
	);
	let location = useLocation();
	let matches = useMatches();
	let navigation = useNavigation();
	// Trigger manual scroll restoration while we're active
	React.useEffect(() => {
	window.history.scrollRestoration = "manual";
	return () => {
	window.history.scrollRestoration = "auto";
	};
	}, []);
	// Save positions on unload
	useBeforeUnload(
	React.useCallback(() => {
	if (navigation.state === "idle") {
	let key = (getKey ? getKey(location, matches) : null) || location.key;
	savedScrollPositions[key] = window.scrollY;
	}
	sessionStorage.setItem(
	storageKey || SCROLL_RESTORATION_STORAGE_KEY,
	JSON.stringify(savedScrollPositions)
	);
	window.history.scrollRestoration = "auto";
	}, [storageKey, getKey, navigation.state, location, matches])
	);
	// Read in any saved scroll locations
	React.useLayoutEffect(() => {
	try {
	let sessionPositions = sessionStorage.getItem(
	storageKey || SCROLL_RESTORATION_STORAGE_KEY
	);
	if (sessionPositions) {
	savedScrollPositions = JSON.parse(sessionPositions);
	}
	} catch (e) {
	// no-op, use default empty object
	}
	}, [storageKey]);
	// Enable scroll restoration in the router
	React.useLayoutEffect(() => {
	let disableScrollRestoration = router?.enableScrollRestoration(
	savedScrollPositions,
	() => window.scrollY,
	getKey
	);
	return () => disableScrollRestoration && disableScrollRestoration();
	}, [router, getKey]);
	// Restore scrolling when state.restoreScrollPosition changes
	React.useLayoutEffect(() => {
	// Explicit false means don't do anything (used for submissions)
	if (restoreScrollPosition === false) {
	return;
	}
	// been here before, scroll to it
	if (typeof restoreScrollPosition === "number") {
	window.scrollTo(0, restoreScrollPosition);
	return;
	}
	// try to scroll to the hash
	if (location.hash) {
	let el = document.getElementById(location.hash.slice(1));
	if (el) {
	el.scrollIntoView();
	return;
	}
	}
	// Opt out of scroll reset if this link requested it
	if (preventScrollReset === true) {
	return;
	}
	// otherwise go to the top on new locations
	window.scrollTo(0, 0);
	}, [location, restoreScrollPosition, preventScrollReset]);
	}

CodeSandbox demo

Very Bad patch fix

In my app at work, I'm working around this by using patch-package to simply use document.querySelector('#content-pane') instead of window. This is a little scary, but it seems to work quite well. #content-pane is in layouts so we know it will more or less always be there.

diff --git a/node_modules/react-router-dom/dist/index.js b/node_modules/react-router-dom/dist/index.js
index aeec512..b617027 100644
--- a/node_modules/react-router-dom/dist/index.js
+++ b/node_modules/react-router-dom/dist/index.js
@@ -796,6 +796,19 @@ function useScrollRestoration(_temp3) {
   let matches = useMatches();
   let navigation = useNavigation(); // Trigger manual scroll restoration while we're active
 
+  // HACK: Scroll restoration doesn't work out of the box (issue #1155) because
+  // the container that scrolls is the content pane, one of the page-level grid
+  // cells. So instead of scrolling window, we pull that element directly by ID
+  // and use it instead. In the unlikely event it's not there, fall back to
+  // window (and likely do nothing).
+  const getScrollTarget = () => document.querySelector('#content-pane') || window;
+
+  // window has scrollY but normal elements have scrollTop
+  const getScrollY = () => {
+    const el = getScrollTarget();
+    return el ? el.scrollY || el.scrollTop : undefined;
+  }
+
   React.useEffect(() => {
     window.history.scrollRestoration = "manual";
     return () => {
@@ -806,7 +819,7 @@ function useScrollRestoration(_temp3) {
   useBeforeUnload(React.useCallback(() => {
     if (navigation.state === "idle") {
       let key = (getKey ? getKey(location, matches) : null) || location.key;
-      savedScrollPositions[key] = window.scrollY;
+      savedScrollPositions[key] = getScrollY();
     }
 
     sessionStorage.setItem(storageKey || SCROLL_RESTORATION_STORAGE_KEY, JSON.stringify(savedScrollPositions));
@@ -825,7 +838,7 @@ function useScrollRestoration(_temp3) {
   }, [storageKey]); // Enable scroll restoration in the router
 
   React.useLayoutEffect(() => {
-    let disableScrollRestoration = router == null ? void 0 : router.enableScrollRestoration(savedScrollPositions, () => window.scrollY, getKey);
+    let disableScrollRestoration = router == null ? void 0 : router.enableScrollRestoration(savedScrollPositions, () => getScrollY(), getKey);
     return () => disableScrollRestoration && disableScrollRestoration();
   }, [router, getKey]); // Restore scrolling when state.restoreScrollPosition changes
 
@@ -837,7 +850,7 @@ function useScrollRestoration(_temp3) {
 
 
     if (typeof restoreScrollPosition === "number") {
-      window.scrollTo(0, restoreScrollPosition);
+      getScrollTarget().scrollTo(0, restoreScrollPosition);
       return;
     } // try to scroll to the hash
 
@@ -856,8 +869,7 @@ function useScrollRestoration(_temp3) {
       return;
     } // otherwise go to the top on new locations
 
-
-    window.scrollTo(0, 0);
+    getScrollTarget().scrollTo(0, 0);
   }, [location, restoreScrollPosition, preventScrollReset]);
 }
 

More general approach

Obviously hard coding an element doesn't make sense for the real library. Here are some ways I can picture it working:

<ScrollRestoration getScrollTarget={() => document.querySelector('#content-pane')} />

and in the library:

const getScrollTarget = () => props.getScrollTarget() || window;

Calling document.querySelector in React is usually not a thing we want to do, so maybe it should be a ref instead. I think this would require putting ScrollRestoration next to your scroll container so you can get the ref:

const ContentPane = () => {
  const ref = useRef(null)
  return (
    <>
      <ScrollRestoration scrollTargetRef={ref} /> 
      <div ref={ref}>...</div>
    </>
  )
}

In both cases I think falling back to window should be ok, because generally it will do nothing. Though maybe that's only true in my use case because we've made sure the whole page doesn't scroll. So maybe it's safer not to fall back, and instead just don't do anything if the ref is null or if the selector function comes back null.

[Antonio-Bennett]

Dude you are a saviour!! Plus helped me to learn about patch-package which I did not know before :) worked like a charm!

[ryanflorence]

I've built a hook to restore scroll of individual elements:

function SomeComp() {
  useElementScrollRestoration("content-pane");

  return (
    <div id="content-pane">
      {/* ... */}
    </div>
  )
}

And then the inside of that looks a whole lot like our code inside of <ScrollRestoration>. They ought to be able to share almost all of the same code.

I'd love to add this hook. If you or someone else wants to take this on I'd love to offer a few tips on how I think I'd implement it.

[david-crespo]

Sure, I'd happily make the PR. How do you propose to get around the scrollY vs. scrollTop thing? Do you think it should also accept a ref instead of an ID? That seemed the more Officially Correct way to me.

[david-crespo]

#9573

[litera]

Would be a better hook if it was called useScrollRestorationRef and then set the ref on the element:

function SomeComp() {
  const ref = useScrollRestorationRef(null);

  return (
    <div ref={ref}>
      ...
    </div>
  )
}

[esmalleydev]

Ran into this issue as well, would love to be able to pass <ScrollRestoration> a ref.

[NestorRV]

I have a similar situation to the one showed in the CodeSandbox demo. I'm using a big <div> as a grid to build a grid of cards. If I scroll down (going through the div) and click back and forward, the position is not retained...

[david-crespo]

My above hack still works for scrolling to top on forward navigation, but when I upgraded from 6.4.2 to 6.6.1, I noticed that scroll restore on back nav doesn't work anymore — it always scrolls to top. What's especially odd is I put in a console.log at the spot where it is supposed to be restoring, and it seems to be doing what I expect it to do, i.e., the scroll restoration number is present and it's a reasonable number, and the target element is also there with a reasonable offsetHeight. In any case, happy to pick #9573 back up or redo it when @ryanflorence has guidance.

[shish]

I am also hitting a practically identical issue (my app uses flexbox for static header / scrollable body / static footer) -- being able to pass a ref to ScrollRestoration sounds ideal :)

[shish]

I'm sure the component could be altered to support a more advanced nested scroll use-case, but it introduces edge cases that would need to be thought through. Like what if when you come back to that location the scrollElement is no longer present for some reason?

Using a ref seems like it would fix this

• If ref is undefined, the developer is intending that we use the window position
• If ref is defined, the developer is intending that we use the element position
  • if the ref is populated, then we save and restore that element
  • if the ref is empty, we do nothing

Does that work? Are there other edge cases I'm not thinking of?

("What if we want to support multiple scrolled elements side-by-side?" seems like a potential case, but my answer right now is "this change is designed to support the common use-case of having a single scrolling element, and only that case; supporting multiple elements would probably require more significant API and internal changes than adding a single optional parameter")

[jrnail23]

@ryanflorence, would you mind sharing your useElementScrollRestoration implementation?

[jrnail23]

@david-crespo, I've been pulling my hair out all day trying to get this working, but now I'm running into a similar problem that you had -- when it's time to restore the scroll, the ref to my scroll container is null. Did you find a fix for that issue?

[jrnail23]

FWIW, I got it working using the id of the scroll container instead of using a ref.

[jrnail23]

It may be a good idea to support both refs and element IDs in the final implementation, because of this issue. It can be such a pain in the ass to deal with refs like that, particularly when their elements are deeper in the tree, and as such, often not rendered yet.

[david-crespo]

I feel like if you can get working with an ID but not a ref, something must be a little off. Your scrolling container should be high in the tree and not conditionally rendered. In the issue I mentioned in the PR, my problem was not that the ref was undefined, but that the div wasn't at its full height yet.

[jrnail23]

I think my issue is probably related to our scrolling container itself -- it's a component provided by our design system library that supports sticky headers/footers, etc., and I don't really have any control over its innards.

[jrnail23]

Cross-posting from #10468 (comment)

Just some feedback from trying this on my own: maybe consider supporting elementId as well as elementRef (presumably mutually exclusive) -- I was able to get this PR's general approach working in my app using elementId, but still having trouble getting it to work with elementRef. In my case, elementRef.current is still empty when it's time to restore the scroll position, so it never gets restored.

I'm really having a hard time understanding how to ensure the scroll container's ref gets populated by the time the scroll restore happens. If ScrollRestoration is placed higher in the React tree than your scroll container, is that even possible? What am I missing here?

I also wanted to add a specific use case we have, to hopefully get feedback and maybe inform future design decisions:

We've got a scrollable list of items, and clicking one navigates to a detail page. That detail page has a "Back to List" link, where when clicked, should navigate back to the list view, restoring the scroll position to the initially clicked item. While we also want scroll restore to work on the browser's back button and have its state survive a reload, that "Back to List" link isn't just a navigate(-1) because that detail page also has stuff you can do (e.g., flip through images using a carousel, or select sub-details to view) that would push new locations (via query string variables), but still stay on the same page (pathname).

For the record, that initial scrollable list is a component itself, with things like optional sticky headers/footers, so window.scrollTo isn't appropriate, and while it's not at the top of the React tree, it's reasonably close. As I mentioned above, I just can't seem to bend the implementation in #10468 to my will to get this working at all, nevermind the "Back to List" link, which likely isn't directly possible with that PR's approach.

FWIW, we made all this work using React Router v5, although I'm not particularly proud of that implementation, TBH. The key for us with RRv5 was that the Link component's to prop accepted a function, whereby when one of the list item links are clicked, we'd capture the container's scroll position in a previousLocation prop in location state on navigate. I was able get this mostly working by hacking together a customized version of useLinkClickHandler, but it's pretty ugly, and I'd love to find a cleaner way to do this.

[martpie]

Adding my use-case to this thread. One of the most requested feature for my Electron app (museeks.io) is scroll restoration between views. Some views may have thousand of elements in them, and losing context when switching from one to the next is tedious.

Why not use body/window? Because we have a fixed header and footer, as most desktop applications, and it doesn't make sense to have an overflow on the whole page.

It would awesome to see an official solution here :D

[jnorvell]

I am also having this issue. My problem, which has also been state above, is that <ScrollRestoration> only seems to work at the window level, and if the scrollable content is further down the hierarchy, it does not seem to work properly. I'm using v6.15.0. For sure that are many fringe cases that may not be practically supportable by a general library, but basic cases like scrollable components within a page seems like a reasonable request.

[jnorvell]

The current version is now v6.20.0. Just checking to see if there is an official solution for this issue scheduled for a specific release.

[brophdawg11]

FWIW @kentcdodds just released this package yesterday https://github.com/epicweb-dev/restore-scroll

[Virthuss]

Sadly I'm having issues with https://github.com/epicweb-dev/restore-scroll
Is there any plan to implement a clean way to easily restore container's scrolling position for 6.21.3 or following ? An official solution would truly be awesome, either trough a hook or with the basic ScrollRestoration component :)

[bartley20]

Thanks for the workaround! It's really unfortunate that ScrollRestoration doesn't support specifying an element rather than the window

[CestDiego]

+1 to needing resotre scroll position of scrollable divs that aren't window.

[CestDiego]

Moreover it should be able to restore both: To a place in window where the div is showing and also the place inside the div. :)

[cristianrgreco]

I also ran into this. I ended up migrating from react-router to tanstack router which supports this. Only took a few minutes and it works as you'd expect: https://tanstack.com/router/v1/docs/framework/react/migrate-from-react-router