Conditionally Block Navigation - nextjs - appDir

[srowe0091]

Summary

With the removal of router events in the NextJs 13 apps, how are we supposed to block navigation based on a conditional flag?

Ideally we want a custom UI alert to appear when the user tries to navigate within the application, as well as cover the case of a browser navigation (back/forward/refresh) and have the browsers default alert prompt appear.
Both cases should either accept/decline the navigation and either preserve or update the URL based on which action was taken.

There's no mention of this anywhere and it seems like none of the "Advanced Routing Patterns" solve this.

Additional information

No response

Example

No response

[fredericrous]

I'm looking for the same feature or at least an official recommendation on why we shouldn't implement this feature to show to my PO and UX 🤣

Apparently you should be able to implement this feature by listening to beforeHistoryChange event:
👉 https://nextjs.org/docs/api-reference/next/router#usage-6

I also found an article of someone patching react router to implement this feature
👉 https://betterprogramming.pub/prevent-route-changes-and-unsaved-data-loss-in-next-js-f93622d73791

However I haven't tried any of these yet. My company has not migrated to NextJs yet

other peope are asking for this feature at:

• Detect when user leaves the page #9662 (88 people asking for the feature)
• Client side navigation interceptors #15985 (an idea of generic design)

[srowe0091]

@fredericrous Even then with those proposed hacks, it doesn't solve the problem for NextJs 13, where the router events have been removed entirely.

[skworden]

did you find a solution?

[srowe0091]

No, I couldn’t find a solution

[nabildroid]

Can't you use client side component that handle Just that

Component..
Use effect..

Return null

[srowe0091]

As far as i know, no it can’t be done like that. Depending on the type of navigation it is whether it’s a hard or soft navigation, nextjs hasn’t provided an example of preventing the user from leaving the page.

[nicolasthy]

Looks like it's not yet supported on the app dir

router.events is not currently supported. See below.

Could there be any alternative to prevent it? None of the above are working solutions for the app dir.

[srowe0091]

none that I came across. Being that this issue is months old and hasn't gotten much attention, I'm not sure what to think now. Searching through google you'll find lots of results asking the same thing.

[nicolasthy]

Only solution I found is to rollback to pages but honestly this is a no go for me because it would require too much dev...

[jonsoku-dev]

I want an official answer..

[run4w4y]

I recently came across the same problem, and did not find an official solution for this case either 😅
So I tried deriving my own solution for this and came up with the following: https://gist.github.com/run4w4y/329f14be5e0574bef0be81e79074b398

In short, it creates a mutation observer to track down all a nodes that appear in the DOM, attaches click listeners and then handles the route changes events logic inside those. I have also replaced all uses of useRouter from next/navigation with my own useRouter hook to achieve the same handling for router.push calls.

While what I had done feels incredibly hacky, is definitely not well-tested and may or may not have an unpleasant smell, I think it works in my case and solves the problem for the time being for me. Would be happy if I could get some feedback on this or if this helps someone else as well :)

[jonsoku-dev]

I want an official answer..

[run4w4y]

Hello, I've got around to publishing my gist above as an npm package with a decent README that showcases the usage for blocking navigation! Please check out the repo here, you could give it a try while we are waiting for the official solution :)

[fedetorre]

I have the same problem, we are mirgrating from page router as encouraged by vercel team but we cannot finish the migration due to this lack of feature. An official answer is appreciated!
Thank you!

[sahmed007]

I don't know why there is no official answer to this as of now. This is needed for complex use-cases such as building an online exam tool where navigating away from the page must be blocked or even complex forms.

[abdelrahman725]

I would then suggest opening the exam in a new tab (now no broswer backward/forward) history exists, disable all the Link components that may appear in the exam component, for example conditionally setting this CSS pointer-events: none; on the Link components.

Now the only thing left is warn users before reloading or closing the tab which can be accomplished by writing the following code in a UseEffect hook inside the exam component

useEffect(() => { window.onbeforeunload = () => { return true } return () => { window.onbeforeunload = null } }, [])

[iampava]

This is very weird to me. Why would you remove them?

[shafkathullah]

See if this helps, https://usehooks.com/usepageleave, they say

This hook is beneficial for scenarios where you need to perform specific actions when a user leaves your webpage, such as saving user progress, displaying a confirmation prompt, or triggering analytics events.

[JonJamesDesign]

There are so many discussion threads on this issue all over this repo and yet no official answer from vercel on any of them.

[mrksph]

@timneutkens @Timer can we have some feedback on this?

[cgfeel]

Intercept route changes at the NextJS app router mode

Demo：[codeSondbox]

cf6e2e9c42a4f29b1dacadffb58c9a1f_723815601830_v_1702122801840414.mp4

source code: https://github.com/cgfeel/next.v2/tree/master/routing-file/src/app/leaving/proxy

Use this Provider in your layout at the app root directory：https://github.com/cgfeel/next.v2/blob/master/routing-file/src/components/proxyProvider/index.tsx

'use client'

import { usePathname, useSearchParams } from "next/navigation";
import Script from "next/script";
import { FC, PropsWithChildren, createContext, useEffect, useState } from "react";

const ProxyContext = createContext<ProxyInstance>([undefined, () => {}]);

const ProxyProvider: FC<PropsWithChildren<{}>> = ({ children }) => {
    const [tips, setTips] = useState<string|undefined>();
    const msg = tips === undefined ? tips : (tips||'Are you sure want to leave this page?');

    const pathname = usePathname();
    const searchParams = useSearchParams();

    const url = [pathname, searchParams].filter(i => i).join('?');
    useEffect(() => {
        setTips(undefined);
    }, [url, setTips]);

    useEffect(() => {
        const handleBeforeUnload = (event: BeforeUnloadEvent) => {
            if (msg === undefined) return msg;
            
            event.preventDefault();
            event.returnValue = msg;
            
            return msg;
        };

        const script = document.getElementById('proxy-script');
        if (script) {
            script.dataset.msg = msg||'';
            script.dataset.href = location.href;
        }

        window.addEventListener("beforeunload", handleBeforeUnload);
        return () => {
            window.removeEventListener("beforeunload", handleBeforeUnload);
        }
    }, [msg]);

    return (
        <ProxyContext.Provider
            value={[msg, setTips]}
        >
            <Script
                strategy="afterInteractive"
                id="proxy-script"
                dangerouslySetInnerHTML={{
                    __html: `(() => {
                        const originalPushState = history.pushState.bind(history);
                        let currentPoint = 0;
                        let point = 0;
                        window.history.pushState = function(state, title, url) {
                            state.point = ++point;
                            currentPoint = point;
                            originalPushState(state, title, url);
                        };
                        const originalReplaceState = history.replaceState.bind(history);
                        window.history.replaceState = function(state, title, url) {
                            state.point = currentPoint;
                            originalReplaceState(state, title, url);
                        };
                        window.addEventListener('popstate', function (event) {
                            const { state: nextState } = event;
                            const isback = currentPoint > nextState.point;

                            currentPoint = nextState.point;

                            const script = document.getElementById('proxy-script');
                            if (!script || location.href === script.dataset.href) return;

                            const msg = script.dataset.msg||'';
                            const confirm = msg == '' ? true : window.confirm(msg);
                            if (!confirm) {
                                event.stopImmediatePropagation();
                                isback ? history.forward() : history.back();
                            }
                        });
                    })()`,
                }}
            ></Script>
            {children}
        </ProxyContext.Provider>
    );
};

export type ProxyInstance = [
    string|undefined, (tips?: string) => void
]

export { ProxyContext };

export default ProxyProvider;

[heecheon92]

This one looks really promising.

[plrthink]

Great, but it seems not working as expected when navigating use browser forward and back button. It do block the back button, but not the forward, and the route be persisted but the history is changed.

[cgfeel]

@plrthink By listening to popstate, you can block the back button as well as the forward button.

[esponges]

Interesting, as per your shared sandbox what prevents navigating with back/next/reload it's the custom script and the custom Button component and finally what blocks navigation is what makes tips to be truthy, in this case caused the existence of any input in the form.

[JonJamesDesign]

I created a solution for this in the end by creating an <UnsavedChangesProvider /> component that wraps my app in the root layout.tsx.

You can read how to implement the same in your app here: How-to: Handle unsaved page changes with NextJS app router

[gcphost]

How about something that isn't behind a paywall?

[SteffenKeller]

The article is behind a paywall but indeed helped me a lot to build a working unsaved changes alert

[ayush4345]

How about something that isn't behind a paywall?

https://freedium.cfd/https://medium.com/@jonjamesdesigns/how-to-handle-unsaved-page-changes-with-nextjs-app-router-65b74f1148de

[JonJamesDesign]

@gcphost rather than simply pasting a few blocks of code, I spent one of my weekend afternoons writing an in-depth article, explaining both the problem and solution in detail.

I post shorter free, non-paywalled content on Medium, and also contribute code snippets and solutions on GH, SO etc. all the time.

[dgabriele]

Hmmm... still nothing on this. This is so damn lame. It's been awhile. Is there really no update on this yet?

[Afellman]

I am looking for a solution for this as well

[kevinwolfcr]

I made an useInterceptAppRouter hook that monkey-patches the AppRouterContext:

function useInterceptAppRouter<TMethod extends keyof AppRouterInstance>(
  method: TMethod,
  interceptFn: (original: AppRouterInstance[TMethod], ...args: Parameters<AppRouterInstance[TMethod]>) => void,
) {
  const appRouter = use(AppRouterContext);

  useEffect(() => {
    if (!appRouter) throw new Error("useInterceptAppRouter must be used within an App Router context");
    const originalMethod = appRouter[method];

    appRouter[method] = ((...args: Parameters<AppRouterInstance[TMethod]>) => {
      console.log("intercepting app router method:", method, "with args:", args);
      interceptFn(originalMethod, ...args);
    }) as AppRouterInstance[TMethod];

    return () => {
      appRouter[method] = originalMethod;
    };
  }, [appRouter, method, interceptFn]);
}

And this is how I use it for enabling view transitions:

function ViewTransitioner() {
  const handleViewTransition = <TArgs extends unknown[]>(
    originalMethod: (...args: TArgs) => unknown,
    ...args: TArgs
  ) => {
    if (!document.startViewTransition) {
      originalMethod(...args);
      return;
    }

    document.startViewTransition(() => {
      originalMethod(...args);
    });
  };

  useInterceptAppRouter("back", handleViewTransition);
  useInterceptAppRouter("forward", handleViewTransition);
  useInterceptAppRouter("push", handleViewTransition);
  useInterceptAppRouter("refresh", handleViewTransition);
  useInterceptAppRouter("replace", handleViewTransition);

  return null;
}

[callumjg]

Thanks @kevinwolfcr. I was facing this issue with a page navigation prompt to handle unsaved changes (migrating from the pages router) and this solution works a charm. Here's a basic implementation:

function useInterceptAppRouter<TMethod extends keyof AppRouterInstance>(
  original: TMethod,
  interceptFn: (original: () => void, args: Parameters<AppRouterInstance[TMethod]>) => void,
): void {
  const appRouter = use(AppRouterContext);

  useEffect(() => {
    if (!appRouter) throw new Error("useInterceptAppRouter must be used within an App Router context");
    const originalMethod = appRouter[original];

    appRouter[original] = ((...args: Parameters<AppRouterInstance[TMethod]>) =>
      // @ts-expect-error args is not tuple?
      interceptFn(() => originalMethod(...args), args)) as AppRouterInstance[TMethod];

    return () => {
      appRouter[original] = originalMethod;
    };
  }, [appRouter, original, interceptFn]);
}

const PageNavigationPrompt: React.FC<{ shouldConfirm: boolean }> = ({ shouldConfirm }) => {
  const [showConfirmationModal, setShowConfirmationModal] = useState<boolean>(false);
  const [forward, setForward] = useState<() => void>();

  const proceedToForwardURL = useCallback((): void => forward?.(), [forward]);
  const handleViewTransition = useCallback(
    (originalMethod: () => void) => {
      if (!shouldConfirm) return originalMethod();
      setShowConfirmationModal(true);
      setForward(() => originalMethod); // use function to set state so react doesn't invoke the function
    },
    [shouldConfirm],
  );

  useInterceptAppRouter("back", handleViewTransition);
  useInterceptAppRouter("forward", handleViewTransition);
  useInterceptAppRouter("prefetch", handleViewTransition);
  useInterceptAppRouter("push", handleViewTransition);
  useInterceptAppRouter("refresh", handleViewTransition);
  useInterceptAppRouter("replace", handleViewTransition);

  return (
    <DestructiveActionModal
      open={showConfirmationModal}
      onCancel={() => setShowConfirmationModal(false)}
      onConfirm={proceedToForwardURL}
    />
  );
};

[cbovis]

Thanks @callumjg this is a great suggestion.

It's worked well for me with the push and replace actions although forward and back are still a bit problematic. I have some additional complexity which requires access to the href being transitioned to so that I can determine whether the pathname is changing or whether navigation is within the same pathname (query change) before deciding whether to block the transition or not. I can access that for push/replace but not for forward/back. Your solution is a great start though!

[Nubebuster]

Thanks @callumjg this is a great suggestion.

It's worked well for me with the push and replace actions although forward and back are still a bit problematic. I have some additional complexity which requires access to the href being transitioned to so that I can determine whether the pathname is changing or whether navigation is within the same pathname (query change) before deciding whether to block the transition or not. I can access that for push/replace but not for forward/back. Your solution is a great start though!

Did you find a solution for forward/back?

[callumjg]

No, but still curious if anyone else has.

[Nubebuster]

@cbovis See previous comments

[seblondono]

I would also hope to get an official response from the Next team on this, as there are some valid use cases where this functionality would be useful.

However, this is #49532 (comment) I made on a related issue. TL;DR persists user's unfinished form state on session storage instead of preventing route transition. Better UX, smaller tech effort.

[mZubu10]

Is there any solution for it now?

[0xmecca]

Try using this -- ended up working for me: https://use100hooks.vercel.app/tools/usePageLeave#install-section

[Surm4]

how about a wrapper component for anchors and buttons which use e.g. router.push that would prevent redirect if some unwanted condition is true?

[mutais]

Any update on this issue,
if it is react-router I can use
https://reactrouter.com/en/main/hooks/use-blocker
But in nextjs there is no equivalent method to support block navigation

[Surm4]

I use a simple workaround like this. In the header, breadcrumbs, navbar I placed a navigation with links and buttons, so I just prevent clicking them by blocking the parent, for my case it just works

[hayata-suenaga]

Asking the same question (i.e. how to listen to the popstate event in an App Router app) on Stack Overflow. Also, asking @leerob on X 🙃

[ypresto]

Finally I created a library for showing page leave confirmation in Next.js .

https://github.com/LayerXcom/next-navigation-guard

It works with both App Router and Pages Router.
Also supports custom dialog component.

How it works is described here:
https://speakerdeck.com/ypresto/cancel-next-js-page-navigation-full-throttle

[killthecreator]

Bless you, sir, works like charm, but unfortunately does not work for me with back/forward buttons. "next": "^14.2.14", Chrome 129 on macOS (Sonoma)

[ypresto]

@killthecreator Are you using latest v0.1.1 ? Also please try the demo page.

[killthecreator]

Yes chief, latest version. Your demo works for me as well

[ypresto]

Thank you! I’ll check for compatibility with your Next.js version. It is also appreciated if you can provide the code and a screen recording.

[killthecreator]

Cannot send u a screen recording unfortunately, but here is the screen of the hook i made:

[Dallair220]

How can it be that after more than 1.5 years there is no non-hacky solution? Come on, Vercel

[ArtemGrachov]

I also implemented a monkey-patching solution. Similar to the ones above but a bit simpler.

import { usePathname, useRouter, useSearchParams } from 'next/navigation';
import { useEffect } from 'react';

type RouterEvents = 'beforeRouteChange' | 'afterRouteChange';

type CallbackResult = boolean | void;
type Callback = () => Promise<CallbackResult> | CallbackResult;

export const useRouterEvents = (() => {
  let patched = false;

  const listeners: Record<RouterEvents, Array<Callback>> = {
    beforeRouteChange: [],
    afterRouteChange: [],
  };

  const eventHandler = async (eventName: RouterEvents) => {
    const arr = listeners[eventName];

    return await Promise.all(arr.map(cb => cb()));
  }

  const addEventListener = (eventName: RouterEvents, callback: Callback) => {
    const arr = listeners[eventName];
    arr.push(callback);
  }

  const removeEventListener = (eventName: RouterEvents, callback: Callback) => {
    const arr = listeners[eventName];
    listeners[eventName] = arr.filter(cb => cb !== callback);
  }

  return () => {
    const router = useRouter();
    const pathname = usePathname();
    const searchParams = useSearchParams();

    useEffect(() => {
      if (!patched) {
        const _back = router.back;
        router.back = async function() {
          const result = await eventHandler('beforeRouteChange');

          if (result.includes(false)) {
            return
          }

          // @ts-ignore
          _back(...arguments);
        }

        const _forward = router.forward;
        router.forward = async function() {
          const result = await eventHandler('beforeRouteChange');

          if (result.includes(false)) {
            return
          }

          // @ts-ignore
          _forward(...arguments);
        }

        const _push = router.push;
        router.push = async function() {
          const result = await eventHandler('beforeRouteChange');

          if (result.includes(false)) {
            return
          }

          eventHandler('beforeRouteChange');
          // @ts-ignore
          _push(...arguments);
        }

        const _replace = router.push;
        router.replace = async function() {
          const result = await eventHandler('beforeRouteChange');

          if (result.includes(false)) {
            return
          }

          // @ts-ignore
          _replace(...arguments);
        }

        patched = true;
      }
    }, []);

    useEffect(() => {
      return () => {
        eventHandler('afterRouteChange');
      }
    }, [pathname, searchParams]);

    return {
      addEventListener,
      removeEventListener,
    };
  }
})();

And how to use it where you need:

  useEffect(() => {
    const handler = () => {
      return new Promise<boolean>(resolve => {
        setTimeout(() => {
          resolve(true)
        }, 5000)
      })
    }

    addEventListener('beforeRouteChange', handler);

    return () => {
      removeEventListener('beforeRouteChange', handler);
    }
  }, [])

In the example above, the navigation is blocked for 5s.

How it works?
Next.js router methods are monkey-patched, and it becomes possible to subscribe to router update events. If the event handler returns false or Promise<false> result, navigation is cancelled. You can use Promise if you need to do a request to the server or wait until user confirm or reject the navigation.

Also, you can simply subscribe to router change events to do what you want and return nothing. For example, trigger some Google Analytic events or whatever.

This approach does not require any additional usage of Context API. The hook is returned from the self-invoked function, which patches router events once only and also stores subscription callbacks.

This solution also does not solve a case when you use browser back/forward buttons. I think the only way to solve this is to call https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event