Opt out of scroll restoration when using browser back buttons

[controversial]

Describe the feature you'd like to request

There is a clear way to opt out of Next.js scroll restoration when using Link or router.push: just pass { scroll: false }. However, I haven't found a clear way to opt out of scroll restoration when using the browser back/forward buttons.

I spent a little while reading the source of the popState handler, and it seems like the router will always jump either to the scroll position in sessionStorage or to the top of the page.

Describe the solution you'd like

Ideally, there would be some kind of router configuration option by which an app could opt out of the router messing with scroll position completely.

Describe alternatives you've considered

I've considered trying to mess with the scroll value stored in sessionStorage during onPopState, but this seems like a really convoluted workaround that might not hold up in future Next.js releases.

[controversial]

I’ve found a pretty good solution in the following:

router.beforePopState((state) => {
  state.options.scroll = false;
  return true;
});

[Timer]

Next.js should not reset the scroll position to 0,0 on back or forwards navigation. Could you please share a reproducible demo for this behavior? We have tests covering this in Chrome.

[controversial]

Sure, @Timer:

I created a repository showing the behavior by the following steps:

1. created a new app with create-next-app
2. I duplicated the example page to create two pages, A and B, with a link between them, and duplicated some of the content to let the pages scroll
3. I added a useEffect hook to set window.history.scrollRestoration = 'manual', to ensure that the browser is not messing with scroll position at all.

For debugging purposes, I also went into the local node_modules and made the following modification inside this block of next/client/index.tsx, though that change is not captured in the repository. This message indicates when it is Next.js initiating the scroll up to the top of the page, rather than the browser or another piece of code.

  if (input.scroll) {
+   console.log('Scrolling to', input.scroll.x, input.scroll.y);
    window.scrollTo(input.scroll.x,input.scroll.y);
  }

Now, I can navigate from page A to page B, and observe that when I press the browser “back” button, a message is printed to the console indicating that Next.js is scrolling the page to the top. Here’s a video:

https://user-images.githubusercontent.com/10377391/104229558-6d072600-541a-11eb-90b6-0258b6d98e8e.mov

You can see that the console message is printed, indicating that Next.js initiates a scroll to (0, 0).

[Timer]

The behavior you just displayed in video was correct, though.

The scroll should be restored to its location on Page A (the top). I agree the console log is weird, but what happens if you scroll Page A before going to B, and then back to A?

I can't reproduce this issue in a normal app (console.log aside, the scroll doesn't appear to be taking affect even though it's called).

[controversial]

Here's the alternate test case you described. I:

1. scroll down on page A
2. move to page B
3. press “back” to page A

As you can see, the page still jumps to the top of the page, and the scrollTo code in client/index.jsx still executes with (0, 0). Here's a video showing that:

https://user-images.githubusercontent.com/10377391/104344406-1c9bd100-54cb-11eb-87b6-8b4378bd3347.mp4

I'm not sure that even the first behavior I showed was correct, though — given that I set history.scrollRestoration = 'manual' and your comment that “Next.js should not reset the scroll position to 0,0 on back or forwards navigation,” I wouldn't expect that the scroll position would change at all when clicking the back button. What am I missing?

[Timer]

Oh, this seems to be specific to window.history.scrollRestoration = 'manual' being configured as manual and not auto.

I can fix this.

[spaghettiguru]

We are having a problem with this behavior too. @Timer, do you have any planned date when this issue is expected to be fixed? It would help us a lot.

[bayraak]

This issue blocking me too. There is no way to disable this unnecessary behavior for now.

[bayraak]

I can fix this.

I've tried this but it didn't work.

[lipoolock]

Hi @Timer

Can we use

module.exports = {
  experimental: {
    scrollRestoration: true
  }
}

as a workaround while this issue is not officially solved ?

[ndimatteo]

Any updates on this? Also trying to implement custom scroll restoration (via Router.on('routeChangeComplete')), and noticing that on clicking the browser back button, after scrolling down a bit on a page, that it pops it back to the top before my custom restoration happens on the incoming page.

To clarify I have the following in place, per official docs and various recommendations:

1. useEffect that sets window.history.scrollRestoration = 'manual'
2. Next Links have scroll={false} per the docs

This only happens on browser back/forward buttons.

[petrogad]

FYI this worked for me:

import Head from "next/head";

export default function ScrollRestorationDisabler() {
  return (
    <Head>
      {/* Tell the browser to never restore the scroll position on load */}
      <script
        dangerouslySetInnerHTML={{
          __html: `history.scrollRestoration = "manual"`,
        }}
      />
    </Head>
  );
}

[danieljpgo]

FYI this worked for me:

import Head from "next/head";

export default function ScrollRestorationDisabler() {
  return (
    <Head>
      {/* Tell the browser to never restore the scroll position on load */}
      <script
        dangerouslySetInnerHTML={{
          __html: `history.scrollRestoration = "manual"`,
        }}
      />
    </Head>
  );
}

It works with me using the scroll prop in the Link component.

https://nextjs.org/docs/api-reference/next/link#disable-scrolling-to-the-top-of-the-page

[mercteil]

As I understand the scrollRestoration issue persists.

I have checked that when I set experimental: { scrollRestoration: true } on every page change my console gives me:

> window.history.scrollRestoration
> 'manual'

We need the scroll to be restored every time we navigate with the browser. If history.scrollRestauration is set to auto the browser should take care of it, but in my case the browser takes care of it before the previous page is reloaded => means my view jumps and then the previous page is loaded at scroll (0,0).

If I use the experimental feature it should be handled by next.JS somewhere window.history.scrollRestoration = manual, but the result is unfortunately that the scroll position is not restored in production and I end up at (0,0). At least the page is not jumping prematurely before the previous one is loaded.

[dlsso]

Oh, this seems to be specific to window.history.scrollRestoration = 'manual' being configured as manual and not auto.

I can fix this.

I am seeing the same behavior as @controversial regardless of whether I have window.history.scrollRestoration set to manual or auto. Scroll down, navigate away, click back button, get returned to top of page instead of where I was.

Workarounds from @controversial, @lipoolock, @petrogad have no effect either. Note this is "next": "^11.0.1",. Any chance I just need 12 for one of the workarounds to take effect?

[theelk801]

Hi, I also recently ran into this bug. I was trying to figure out what was causing it and in doing so I found a somewhat sketchy but effective workaround.

In my case, I was implementing my own scrolling tracker so I could use framer motion with next. The only time I want something to use window.scrollTo is in my scrolling handler, so I added the following code to it:

useEffect(() => {
  const { scrollTo } = window;
  window.scrollTo = ({ left, top, behavior, allowed }) => {
    if (allowed) {
      scrollTo({ left, top, behavior, allowed });
    }
  };
  return () => (window.scrollTo = scrollTo);
}, []);

And when I call window.scrollTo, I add the allowed argument like so:

window.scrollTo({ left: 0, top: position, allowed: true })

This of course will only work if you're implementing your own scroll tracker like I am, but hopefully it helps people as a temporary workaround. Hopefully the fix comes through soon.

[pwfisher]

To override both Next.js and native scrollRestoration, try useScrollRestoration by @claus:

• https://gist.github.com/claus/992a5596d6532ac91b24abe24e10ae81

[timfuhrmann]

A combination of both beforePopState and window.history.scrollRestoration = 'manual' does the trick for me:

export const Transition: React.FC = ({ children }) => {
    const router = useRouter();

    useEffect(() => {
        router.beforePopState(state => {
            state.options.scroll = false;
            return true;
        });
    }, []);

    return (
         <Script>{`window.history.scrollRestoration = "manual"`}</Script>
        ...
    );
};

No scroll at all when navigation back or forth.

[zachpinfold]

To override both Next.js and native scrollRestoration, try useScrollRestoration by @claus:

• https://gist.github.com/claus/992a5596d6532ac91b24abe24e10ae81

This works for me!

[LarssonHenrik]

To override both Next.js and native scrollRestoration, try useScrollRestoration by @claus: https://gist.github.com/claus/992a5596d6532ac91b24abe24e10ae81

This worked well for me as well!

[batazo]

Hi @Timer

Can we use

module.exports = {
  experimental: {
    scrollRestoration: true
  }
}

as a workaround while this issue is not officially solved ?

Respect

[aroyan]

Why am I still facing this issue? Is this haven't fixed yet? Currently I am using Next 12.1.5

[BiosBoy]

Worked fine for me:

You can enable it in your next.config.js file this way:

module.exports = { experimental: { scrollRestoration: true, }, };

[nhannah]

There is an issue with all of these solutions that I am not sure has been noticed. On iOS WebKit there is a check that a snapshot should only be shown for a back or forward action if shouldRestoreScrollPosition || (currentScrollPosition == snapshot->viewScrollPosition()), shouldRestoreScrollPosition is equivalent to history.scrollRestoration = "auto". Setting history.scrollRestoration = "manual" means the current page must be scrolled to the same position as the page being transitioned to (forward or back) in order for the UI to look "normal" when navigating.

Here is an example on the Target website that uses Next:

https://user-images.githubusercontent.com/608869/187505346-fe887b8b-df52-49e1-8018-7647a2d6c170.mov

Notice if both screens are scrolled to top the snapshot is shown, but Target has some form of scroll restoration it seems so the manual setting screws up the page.

The only solution I found so far for my own project is to check for webkit and not set scrollRestoration to manual in that case, as window.history.scrollRestoration = 'auto' doesn't work for my project anyway this seems to give the desired result.

 if (navigator.userAgent.indexOf('AppleWebKit') != -1) {
      window.history.scrollRestoration = 'auto';
    } else {
      window.history.scrollRestoration = 'manual';
    }

[mosesoak]

@nhannah Thanks for noticing that iOS safari issue! Hopefully the Next authors will take it into account if they ever address this glaring problem. Gatsby has excellent built-in scroll restoration so we've been quite surprised to have to patch it. Users have been posting about it since 2017 🤷

Your sniff is a little too broad though, gets picked up by Firefox. I used,

      // Manual doesn't work well on iOS Safari https://github.com/vercel/next.js/issues/20951#issuecomment-1231966865
      const ua = window.navigator.userAgent.toLowerCase();
      const isMobileSafari = /safari/.test(ua) && /iphone|ipod|ipad/.test(ua);
      window.history.scrollRestoration = isMobileSafari ? 'auto' : 'manual';

I updated the hook to include that and some other niceties at the main gist here: https://gist.github.com/claus/992a5596d6532ac91b24abe24e10ae81?permalink_comment_id=4301903#gistcomment-4301903

[mosesoak]

@tomiviljanen CC @ijjk hi I tried the experimental scroll restoration and it worked pretty well.

It has a few outstanding issues though:

1. scroll doesn't restore on page refresh
2. when going back, if your page has a number of react components, restore happens too fast and it will end up jumping to the bottom of the page (I added a 1ms timeout workaround in my version of the community hook)
3. scroll-behavior: smooth doesn't work well in Next. You jump to the wrong scroll location on new pages a la this post https://github.com/vercel/next.js/issues/3303#issuecomment-371269290 and when going back, instead of the bottom of the page I get an incorrect position that's slightly higher on the page.

I know there are a number of other open issues out there on all of this but just wanted to list these out clearly. Seems that the experimental feature isn't super close to production-ready yet.

When testing the feature, I'd suggest using a full web page with a good amount of content on it, since it seems like React's hydration lifecycle interacts with this and there are little race conditions happening. (I don't mean this as a dig at all, but you might also peek at how Gatsby does theirs as it is quite solid.)

[IshmamR]

A combination of both beforePopState and window.history.scrollRestoration = 'manual' does the trick for me:

export const Transition: React.FC = ({ children }) => {
    const router = useRouter();

    useEffect(() => {
        router.beforePopState(state => {
            state.options.scroll = false;
            return true;
        });
    }, []);

    return (
         <Script>{`window.history.scrollRestoration = "manual"`}</Script>
        ...
    );
};

No scroll at all when navigation back or forth.

Working nicely for me

[rhigdon]

For me it was just the window history scroll restoration

window.history.scrollRestoration = "manual";

Here is a good article I found https://developer.chrome.com/blog/history-api-scroll-restoration/

[kylealwyn]

Dropping a note that experimental.scrollRestoration not working with react-query - had to opt for community hook

[ifahs1]

Describe the feature you'd like to request

There is a clear way to opt out of Next.js scroll restoration when using Link or router.push: just pass { scroll: false }. However, I haven't found a clear way to opt out of scroll restoration when using the browser back/forward buttons.

I spent a little while reading the source of the popState handler, and it seems like the router will always jump either to the scroll position in sessionStorage or to the top of the page.

Describe the solution you'd like

Ideally, there would be some kind of router configuration option by which an app could opt out of the router messing with scroll position completely.

Describe alternatives you've considered

I've considered trying to mess with the scroll value stored in sessionStorage during onPopState, but this seems like a really convoluted workaround that might not hold up in future Next.js releases.

Just add this in nextjsconfig Tested and working 👍

module.exports = { experimental: { scrollRestoration: true, }, };

[gregg-cbs]

I am using "next": "13.1.6" and i can confirm setting scrollRestoration: true solves the page position issue when going to a previously visited page using browser back and forward buttons. The restoration does not happen when using nexts Link to go to a page that was previously visited which is expected.

module.exports = { experimental: { scrollRestoration: true, }, };

[sahanxdissanayake]

any updates on this? https://www.reddit.com/r/nextjs/comments/139gvr9/how_to_stop_scroll_on_routerpushhref_in_app/

[samcx]

Hi everyone!

I will be closing this issue since this is resolved with scroll: false.

• https://nextjs.org/docs/app/api-reference/components/link#scroll

Feel free to submit a new bug report if you are still experiencing scroll issues!

[controversial]

@samcx This issue is explicitly about controlling the behavior when not using Link, as the original issue clearly describes.

The original issue notes the existence of the scroll prop on Link, and describes why scroll: false does not resolve this issue, since this issue is not about the Link component.

This issue is unresolved and should be reopened.

[samcx]

@controversial Thank you for the clarification—my apologies for not reading the issue correctly.

It might be possible for us to have this experimental API (which only works with Pages Router)

experimental: {
  scrollRestoration: false
 }

to add window.history.scrollRestoration = "manual"; — let me infer with the team to see if that's possible.

[rhd-developers]

@samcx This works in Next 13 dev mode, but in production in standalone mode it doesn't work. Any ideas?

[samcx]

@rhd-developers Are you using Pages Router? If yes, can you provide us a simple that showcases your issue?

[iDVB]

Can we extend the OP question to simply ask how to Opt out completely of any native NextJS scroll management at all? We don't want any solution but our own which is currently working perfectly.

We know scrollRestoration and scrollBehavior are for different purposes but would like to propose that they both fall under scrollManagement with relation to routing.

We are wanting to completely disable native scroll management so that we have complete control over "when" scrollRestoring happens in time. This is because we are implementing complex Page Transition animations that:

• Animates OUT the current page
• Transitions between pages
• Animates IN the target page

Since these animations are timed, we need to control when the restore, or any scrollTo 's happen. These means two things for us: 1) we need to completely disable the native scrollRestoration 2) we need to prevent any native scrollTo's that happen

ISSUE #1: we've tried:

• setting config experimental.scrollRestoration = false
• setting __NEXT_SCROLL_RESTORATION = false
• setting NEXT_PUBLIC_SCROLL_RESTORATION = false

Nothing seems to work, even though we can see many places in the core code that reference this env var

ISSUE #2: there is native code that uses scrollTo regardless of the scrollRestoration setting, and appears to compete with it even when its on.

We have things working by disabling all <Link> with scroll=false (very much, not ideal) And we also need to force window.history.scrollRestoration = 'manual' on each route change. Lastly we will need to patch core NextJS in order to prevent the ISSUE #2 code above from running.

Would LOVE some incite here or guidance if anyone has any.

[samcx]

@iDVB I assume you're using App Router instead of Pages Router? That would explain why that configuration doesn't work (issue #1).

We have things working by disabling all with scroll=false (very much, not ideal)

You could also just create a custom <Link> component by wrapping it.

Would a config to opt out of any window.scrollTo suffice with the recommendation above?

[iDVB]

We ended up expanding on @claus 's ScrollRestoration above. This works with the latest version of NextJS and Page Router, although it may also work with App Router, but we've not tested. The primary purpose of this for us was to haven the ability to control "when" scroll was restored for certain routes where we have custom page transitions that use gsap animation lib.

Added support for:

• calling triggerRestore to allow for you to decide "when" to restore. This is very helpful when you want to create complex page transition animations.
• ignorePattern for routes to not scroll restore at all for
• support for using with libs that also store and restore window.history.scrollRestoration like gsap.

https://gist.github.com/iDVB/4f6ba81d4cdf37dd16fefdfca0fd5777