Route cancellation

[cmwd]

• I have searched the issues of this repository and believe that this is not a duplicate.

Expected Behavior

A method in router API that allows aborting upcoming route change.

Current Behavior

Right now router exposes abortComponentLoad method but it seems to be designed only for internal use and it doesn't work if it's called in routeChangeStart handler. It works only after this piece of code was executed:

async fetchComponent (route, as) {
  let cancelled = false
  const cancel = this.componentLoadCancel = function () {
    cancelled = true
  }

Workaround:

Router.ready(() => {
  Router.router.on('routeChangeStart', () => {
    setTimeout(() => {
      Router.router.abortComponentLoad();
    });
  });
});

Context

This is useful for example when building complex forms and we want to warn a user before he leaves the page without submitting.

Your Environment

ANY

[cmwd]

If someone needs this feature I found that better workaround is just to throw an error in routeChangeStart event handler:

Router.ready(() => {
  Router.router.on('routeChangeStart', () => {
    throw new Error('Abort');
  });
});

[SergiuPlesco]

This is working, but how do you handle this Error?
If you put the code in trycatch block it stops working.

[erikras]

Seems like a reasonable solution would be to abort the routing if the return value from onRouteChangeStart() is === false. That's what I attempted before having to search and find this issue.

[tlackemann]

The workarounds above no longer work in Next.js 4, I believe this is because there are no methods exposed on the router itself that would give us control over this. Particularly, there is no way to expose componentLoadCancel to manually cancel a route

A use-case where this would be helpful is "unsaved changes" dialogs/warnings.

I'm open to making a PR if this is something that would be desired.

[DonovanCharpin]

The workarounds only work for a link clicked but don't work when using browser navigation for instance. I agree with @erikras, that would be really nice to be able to return a boolean in onRouteChangeStart to cancel the route change!

Router.onRouteChangeStart = (url) => {
  if (!window.confirm('You really want to leave?')) {
    return false;
  }
  return true;
}

Unfortunately, onRouteChangeStart is just an event and can't manage any value to return.

[cmwd]

I think it makes sense to cancel route by throwing a custom error.

Router.onRouteChangeStart = (url) => {
  if (!window.confirm('You really want to leave?')) {
    throw new Router.Abort();
  }
}

What do you think?

[DonovanCharpin]

Both work for me as long as we have this feature which is really useful.

I think It's more common to manage this with a boolean but more understandable with this Abort method.

[ryanmeisters]

Did anything like this make it into 5.0? Anybody done something like this in 5.0 yet?

[paulobarcelos]

Also looking for this feature. Working on a editor app and need to be able to cancel route changes in case there are unsaved changes.

[Negan1911]

The only way to work with this was using

Router.router.events.on('routeChangeStart', () => {
    throw new Error('nooo')
})

[justbrody]

@Negan1911 , where do you catch the raised error?

[Negan1911]

@justbrody no need to catch it, it will appear on the console but prevent the navigation

[justbrody]

@Negan1911 , Thanks for the quick reply. I'm trying not to polute the console, people will get nervous seeing errors in the console.

[Negan1911]

@justbrody Yeah i know, my QA got crazy because of that, but nothing to do at this level ¯_(ツ)_/¯¯

[justbrody]

@Negan1911 I'm going to wrap the Router calls with my own implementation for more control.
Nextjs-team, thanks for a great library and I hope the requested feature of @cmwd will someday be implemented.

[thebearingedge]

Also looking for this feature. Working on a editor app and need to be able to cancel route changes in case there are unsaved changes.

I just ended up dumping work-in-progress stuff to localStorage. Asking the user if they want to restore or not when they come back suffices for my scenario (accidental navigation).

[hfossli-agens]

This is a js solution built on top of various contributors (mainly @ryym, @GorkemSahin and @dkershner6 and more)

It supports

• pressing the back button in browser
• pressing the forward button in browser
• reloading in browser
• closing the tab/browser
• navigating within the web app (next.js routing)
• navigating to another URL with address bar (e.g. google.com)

import Router, { useRouter } from "next/router"
import { useRef, useEffect, useCallback } from "react"

const throwFakeErrorToFoolNextRouter = () => {
    // Throwing an actual error class trips the Next.JS 500 Page, this string literal does not.
    throw "Abort route change due to unsaved changes in form. Triggered by useWarningOnExit. Please ignore this error. See issue https://github.com/vercel/next.js/issues/2476"
}

/** @returns {Window?} */
const getWindow = () => typeof window !== "undefined" && window

/** @returns {History.state?} */
const getHistory = () => getWindow()?.history?.state

/**
 * @param {boolean} shouldWarn 
 * @param {string?} message 
 */
export const useWarningOnExit = (shouldWarn = true, message = "Discard unsaved changes?") => {
    const router = useRouter()
    const lastHistory = useRef(getHistory())

    useEffect(() => {
        const storeLastHistoryState = () => {
            lastHistory.current = getHistory()
        }
        router.events.on("routeChangeComplete", storeLastHistoryState)
        return () => {
            router.events.off("routeChangeComplete", storeLastHistoryState)
        }
    }, [router])

    /**
     * @experimental HACK - idx is not documented
     * Determines which direction to travel in history.
     */
    const revertTheChangeRouterJustMade = useCallback(() => {
        const state = lastHistory.current
        if (
            state !== null &&
            history.state !== null &&
            state.idx !== history.state.idx
        ) {
            const delta = lastHistory.current.idx < history.state.idx ? -1 : 1
            history.go(delta)
        }
    }, [])

    const killRouterEvent = useCallback(() => {
        router.events.emit("routeChangeError")
        revertTheChangeRouterJustMade()
        throwFakeErrorToFoolNextRouter()
    }, [revertTheChangeRouterJustMade, router])

    useEffect(() => {
        let isWarned = false

        const routeChangeStart = (url) => {
            if (router.asPath !== url && shouldWarn && !isWarned) {
                isWarned = true
                if (window.confirm(message)) {
                    router.push(url)
                    return
                }
                isWarned = false
                killRouterEvent()
            }
        }

        const beforeUnload = (e) => {
            if (shouldWarn && !isWarned) {
                const event = e ?? getWindow()?.event
                event?.returnValue = message
                return message
            }
            return null
        }

        router.events.on("routeChangeStart", routeChangeStart)
        getWindow()?.addEventListener("beforeunload", beforeUnload)

        return () => {
            router.events.off("routeChangeStart", routeChangeStart)
            getWindow()?.removeEventListener("beforeunload", beforeUnload)
        }
    }, [message, shouldWarn, killRouterEvent, router])
}

export default useWarningOnExit

Example with next.js and react-hook-form

useWarningOnExit(formState.isDirty)

[marko-hologram]

can we use custom modal instead of window.confirm() ?

I'm guessing no since that would allow sites to trap users and not allow them to leave. You can potentially show a custom modal for client side navigations (SPA apps) that are triggered by using in app links, but if user pressed back/forward in their browser I'm quite sure you cannot block that using anything else other than native window.confirm().

[michalpokojski]

unfortulately I've tried using promises but routeChangeStart is not async and route will change before user can make his decision :(

[hateonion]

Yeah same issue here. Async won't block the navigation

[draxx318]

The problem here is when using the broweser's back button the navigation gets blocked but the uri changes. I cant find a ways past that.

[hyousi]

unfortulately I've tried using promises but routeChangeStart is not async and route will change before user can make his decision :(

I think you could try something like this.

export function useLeaveConfirm({ when, message = defaultMessage }: Props) {
    const router = useRouter();
    const confirmed = useRef(false);

    const onRouteChangeStart = useCallback(
        (url: string) => {
            if (!when || confirmed.current) {
                return;
            }
            confirm("Alert", message).then((result) => {
                if (!result) {
                    return;
                }
                confirmed.current = true;
                router.push(url);
            });
            throw "Abort route change by user's confirmation.";
        },
        [when, message, router],
    );

    useEffect(() => {
        router.events.on("routeChangeStart", onRouteChangeStart);

        return () => {
            router.events.off("routeChangeError", onRouteChangeStart);
        };
    }, [onRouteChangeStart, router]);
}

[gentlementlegen]

Here is a working version for TypeScript if anyone needs it. Testing in Chrome, Safari, Opera.

import { useRouter } from 'next/router';
import { useCallback, useEffect, useRef } from 'react';
import { UrlObject } from 'url';

const throwFakeErrorToFoolNextRouter = () => {
  // Throwing an actual error class trips the Next.JS 500 Page, this string literal does not.
  // eslint-disable-next-line @typescript-eslint/no-throw-literal
  throw 'Abort route change due to unsaved changes in form. Triggered by useWarningOnExit. Please ignore this error. See issue https://github.com/vercel/next.js/issues/2476';
};

const getWindow = (): Window | null => (typeof window !== 'undefined' ? window : null);

const getHistory = () => getWindow()?.history?.state;

export const useWarningOnExit = (shouldWarn = true, message = 'Discard unsaved changes?') => {
  const router = useRouter();
  const lastHistory = useRef(getHistory());

  useEffect(() => {
    const storeLastHistoryState = () => {
      lastHistory.current = getHistory();
    };
    router.events.on('routeChangeComplete', storeLastHistoryState);
    return () => {
      router.events.off('routeChangeComplete', storeLastHistoryState);
    };
  }, [router]);

  /**
   * @experimental HACK - idx is not documented
   * Determines which direction to travel in history.
   */
  const revertTheChangeRouterJustMade = useCallback(() => {
    const state = lastHistory.current;
    if (state !== null && history.state !== null && state.idx !== history.state.idx) {
      const delta = lastHistory.current.idx < history.state.idx ? -1 : 1;
      history.go(delta);
    }
  }, []);

  const killRouterEvent = useCallback(() => {
    router.events.emit('routeChangeError');
    revertTheChangeRouterJustMade();
    throwFakeErrorToFoolNextRouter();
  }, [revertTheChangeRouterJustMade, router]);

  useEffect(() => {
    let isWarned = false;

    const routeChangeStart = (url: string | UrlObject) => {
      if (router.asPath !== url && shouldWarn && !isWarned) {
        isWarned = true;
        if (window.confirm(message)) {
          router.push(url);
          return;
        }
        isWarned = false;
        killRouterEvent();
      }
    };

    const beforeUnload = (e: Event | null) => {
      if (shouldWarn && !isWarned) {
        const event = e ?? getWindow()?.event;
        if (event) {
          event.returnValue = Boolean(message);
        }
        return message;
      }
      return null;
    };

    router.events.on('routeChangeStart', routeChangeStart);
    getWindow()?.addEventListener('beforeunload', beforeUnload);

    return () => {
      router.events.off('routeChangeStart', routeChangeStart);
      getWindow()?.removeEventListener('beforeunload', beforeUnload);
    };
  }, [message, shouldWarn, killRouterEvent, router]);
};

export default useWarningOnExit;

[AshMW2724]

Had to make a change to router.events.emit('routeChangeError'); and change it to router.events.emit('routeChangeError', '', '', { shallow: false }); which works perfectly for me. Wish this was built in to Next.JS though.

[PTanwarCS]

Has a bug if the browser's back/forward button is pressed.
Suppose if I am not /edit-profile and I click on back button which should got the /welcome. The confirm popup does gets displayed, but the url also gets changed to /welcome, even if I click on "Cancel button"

[jestebanzapata]

@PTanwarCS Did you find any way to solve the back/forward bug?

[PTanwarCS]

Unfortunately not.

[cuginoAle]

Hi,
my solution below is largely inspired by the comments/code from others in this discussion.

This hook allows me to use a custom modal dialog (not window.confirm) to ask user to confirm whether to proceed or prevent the navigation.

I am not handling the beforeunload event on purpose as I don't think we should handle that scenario.

Usage example:

  // let's assume formDirty is used to toggle the custom hook

  const navigate = useNavigationObserver({
    shouldStopNavigation: formDirty,
    onNavigate: () => {
      setShowModal(true)
    },
  })

The hook requires a boolean and a callback. The former is to toggle navigation interception on/off while the latter is called when a navigation attempt has been made. In my case I show a custom modal by using setShowModal to true.

It returns a method that, if executed, triggers the navigation.

the code:

import { useRouter } from 'next/router'
import { useCallback, useEffect, useRef } from 'react'

const throwFakeErrorToFoolNextRouter = () => {
  // Throwing an actual error class trips the Next.JS 500 Page, this string literal does not.
  // eslint-disable-next-line no-throw-literal
  throw ' 👍 Abort route change due to unsaved changes in form. Triggered by useNavigationObserver. Please ignore this error.'
}

interface Props {
  shouldStopNavigation: boolean
  onNavigate: (nextUrl: string) => void
}

const useNavigationObserver = ({ shouldStopNavigation, onNavigate }: Props) => {
  const router = useRouter()
  const currentPath = router.asPath
  const nextPath = useRef('')

  const killRouterEvent = useCallback(() => {
    router.events.emit('routeChangeError')
    throwFakeErrorToFoolNextRouter()
  }, [router])

  useEffect(() => {
    const onRouteChange = (url: string) => {
      if (shouldStopNavigation && url !== currentPath) {
        nextPath.current = url
        onNavigate(url)
        killRouterEvent()
      }
    }

    router.events.on('routeChangeStart', onRouteChange)

    return () => {
      router.events.off('routeChangeStart', onRouteChange)
    }
  }, [
    currentPath,
    killRouterEvent,
    onNavigate,
    router.events,
    shouldStopNavigation,
  ])

  const navigate = () => {
    router.push(nextPath.current)
  }

  return navigate
}

export { useNavigationObserver }

[vstirbu]

This is gold

router.events.emit('routeChangeError')

[testerez]

This is better:

router.events.emit('routeChangeError', '', '', { shallow: false })

Otherwise, third party listeners of this event that you may have can error because this data is expected.

[armaanshah96]

This is awesome thank you

I had to add a check at the top of the onRouteChange function:

if(nextPath.current === url) return;

That prevents the event from repeatedly getting triggered and killing the router change event when you actually call navigate

Nvm I see your solution below included this

[aleveha]

import { useRouter } from "next/router";
import { useCallback, useEffect, useState } from "react";

const useBeforeUnload = (enabled: boolean) => {
	const handler = useCallback(
		(event: BeforeUnloadEvent) => {
			if (!enabled) {
				return;
			}

			event.preventDefault();
		},
		[enabled]
	);

	useEffect(() => {
		if (!enabled) {
			return;
		}

		window.addEventListener("beforeunload", handler);

		return () => window.removeEventListener("beforeunload", handler);
	}, [enabled, handler]);
};

export const useFormLeave = (isDirty: boolean) => {
	const router = useRouter();

	const [showLeaveModal, setShowLeaveModal] = useState(false);
	const [pathname, setPathname] = useState<string | null>(null);

	useBeforeUnload(isDirty);

	const onRouteChangeStart = useCallback(
		(pathname: string) => {
			if (!isDirty) {
				return;
			}

			setShowLeaveModal(true);
			setPathname(pathname);
			throw "\nRoute change aborted. Please ignore this error";
		},
		[isDirty]
	);

	const removeRouteChangeStart = useCallback(() => router.events.off("routeChangeStart", onRouteChangeStart), [router.events, onRouteChangeStart]);

	const handleUserChoice = useCallback(
		(leave: boolean) => async () => {
			setShowLeaveModal(false);

			if (!leave) {
				setPathname(null);
				return;
			}

			removeRouteChangeStart();

			if (pathname) {
				await router.push(pathname);
			}
		},
		[pathname, removeRouteChangeStart, router]
	);

	useEffect(() => {
		router.events.on("routeChangeStart", onRouteChangeStart);

		return removeRouteChangeStart;
	}, [onRouteChangeStart, removeRouteChangeStart, router.events]);

	return [showLeaveModal, handleUserChoice] as const;
};

[zetary-agba]

From my point for view the most critical point is using throw to stop navigation of next router. It is quite surprised that we need to take plenty of efforts so as to intercept routing in next/router

As earlier comments said not only users but also QAs concern a lot while receiving errors in the console.
So any idea to get rid of throw or we could catch that error somewhere in order to avoid showing console errors?

[juokavom]

Exactly!

[aribowobob]

upvoted this because i got this error on unit test:

[UnhandledPromiseRejection: This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). The promise rejected with the reason "Abort route change. Please ignore this error.".] {
  code: 'ERR_UNHANDLED_REJECTION'
}

[sanderkranz]

window.addEventListener('unhandledrejection', (event: PromiseRejectionEvent) => {
  if (event.reason === 'Abort route change. Please ignore this error.') {
    event.preventDefault()
  }
})

[testerez]

Sharing my version in case it helps anyone. bypassExitConfirmation is necessary so that you can exit the form directly after it's been saved for example.

import useTranslation from 'next-translate/useTranslation'
import { useRouter } from 'next/router'
import { useEffect, useRef } from 'react'

export function useExitConfirmation({
  message,
  enable,
}: {
  message?: string
  enable: boolean
}) {
  const { t } = useTranslation()
  const router = useRouter()
  const bypassConfirmationRef = useRef(false)

  message =
    message ??
    t(
      'Your changes have not been saved. Are you sure you want to leave this page?',
    )
  useEffect(() => {
    const shouldByPassconfimation = () =>
      !enable || bypassConfirmationRef.current
    const handleWindowClose = (e: BeforeUnloadEvent) => {
      if (shouldByPassconfimation()) return
      e.preventDefault()
      return (e.returnValue = message)
    }
    const handleBrowseAway = () => {
      if (shouldByPassconfimation()) return
      if (window.confirm(message)) return
      router.events.emit('routeChangeError')
      throw 'routeChange aborted by user.'
    }
    window.addEventListener('beforeunload', handleWindowClose)
    router.events.on('routeChangeStart', handleBrowseAway)
    return () => {
      window.removeEventListener('beforeunload', handleWindowClose)
      router.events.off('routeChangeStart', handleBrowseAway)
    }
  }, [enable, router.events, t, message])

  return {
    bypassExitConfirmation(value = true) {
      bypassConfirmationRef.current = value
    },
  }
}

[omerman]

Isn't this important enough? It is such a common usecase.. Can someone please take it from the Next team?
after this commit 75d6bda0d2
the snippets above are not working well anymore.. I know idx was not documented, but now the behavior is messed up.

Help us NextJS team 🙏

[testerez]

In fact, looks like quite a few people would like to have a clean way to handle route cancellation:

[marko-hologram]

Yeah not sure how is this not implemented yet. It's not quite uncommon to want to abort a navigation attempt if user didn't save their work.

I'm not sure if Next.js team even gave an official stance regarding this anywhere. At this point, I would at least be happy with an official answer saying why it might not be easy to do or that it's planned sometime in the future or something like that.

[omerman]

If someone from Nextjs's team sees it, I'm willing to pay for this feature to be implemented, it's such a common usecase 🙄

[yuvalkarmi]

Edit: got this to work.

Note that throw new Error("Abort route change by user's confirmation.") does not work and is not equivalent to throwing the string directly: ``throw "Abort route change by user's confirmation."`

The confusion was that eslint was suggesting I throw a new Error instead of a string.
Turns out you do need to throw a string directly.
To disable eslint complaining about this line, add // eslint-disable-next-line no-throw-literal above.

So the complete three lines are:

Router.events.emit('routeChangeError')
// eslint-disable-next-line no-throw-literal
throw "Abort route change by user's confirmation."

[tranduybau]

This is my file, Hope it can help you :D

import { useCallback, useEffect, useMemo, useState } from 'react';
import { useRouter } from 'next/router';

type Props = {
  message?: string;
};

const defaultMessage = '';

function useLeaveConfirm({ message = '' }: Props = {}) {
  const Router = useRouter();
  const [isDirty, setIsDirty] = useState(false);
  const finalMSG = useMemo(() => message || defaultMessage, [message]);

  const onRouteChangeStart = useCallback(() => {
    if (isDirty) {
      // eslint-disable-next-line no-alert
      if (window.confirm(finalMSG)) {
        return true;
      }

      // eslint-disable-next-line @typescript-eslint/no-throw-literal
      throw "Abort route change by user's confirmation.";
    }

    return null;
  }, [isDirty, finalMSG]);

  useEffect(() => {
    Router.events.on('routeChangeStart', onRouteChangeStart);

    return () => {
      Router.events.off('routeChangeStart', onRouteChangeStart);
    };
  }, [Router.events, onRouteChangeStart]);

  useEffect(() => {
    const handleBeforeUnload = () => {
      if (isDirty) {
        return true;
      }

      return undefined;
    };

    if (typeof window !== 'undefined') {
      window.onbeforeunload = handleBeforeUnload;
    }

    return () => {
      if (typeof window !== 'undefined') {
        window.onbeforeunload = null;
      }
    };
  }, [isDirty]);

  return { isDirty, setIsDirty };
}

export default useLeaveConfirm;

How to use:

const { setIsDirty } = useLeaveConfirm();

const onChange = () => {
  setIsDirty(true);
  // your code
}

const onSubmit = () => {
  submit().then(() => {
    setIsDirty(false);
  })
}

[yuvalkarmi]

Thank you!

[yuvalkarmi]

Got this to work! (as of June 21, 2023)

Here's a quick useEffect you can drop into any component, without depending on any additional libraries.

You can find the complete gist right here:
https://gist.github.com/yuvalkarmi/ab7944b2da693c71cf697db6a47e5b5d

But here's the relevant code:

// make sure you import Router and useEffect

import Router from "next/router";
import { useEffect } from 'react';

// then in your component, simply add this useEffect:

const shouldBlockNavigation = true; // set this up however you want

useEffect(() => {
    const nativeBrowserHandler = (event) => {
      if (shouldBlockNavigation) {
        event.preventDefault();
      }
    };

    const nextNavigationHandler = (url) => {
      if (shouldBlockNavigation) {
        if (!window.confirm('Navigate away? Changes you made may not be saved.')) {
          Router.events.emit('routeChangeError')
          // eslint-disable-next-line no-throw-literal
          throw "Abort route change by user's confirmation."
        }
      }
    };

    window.addEventListener('beforeunload', nativeBrowserHandler);
    Router.events.on("beforeHistoryChange", nextNavigationHandler);

    // On component unmount, remove the event listener and finish the upload
    return () => {
      window.removeEventListener('beforeunload', nativeBrowserHandler);
      Router.events.off("beforeHistoryChange", nextNavigationHandler);
    };
  }, [shouldBlockNavigation]);

[tranduybau]

@yuvalkarmi if you use event.preventDefault();, so you don't need the returnValue. I'm surely that. You can less 1 code line :D

[yuvalkarmi]

@trdbau did not check this, but makes sense - updated!

[tranduybau]

@yuvalkarmi https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event#compatibility_notes
Here is the document said:
The HTML specification states that authors should use the Event.preventDefault() method instead of using Event.returnValue to prompt the user. However, this is not yet supported by all browsers.

[yuvalkarmi]

I see - it looks like all modern browsers have Event.returnValue deprecated, so I'm cool removing that line. I kept it in the gist, though added a comment it may no longer be necessary. Thanks!

[cuginoAle]

Hi all,
my requirements for the solution are :

• it should prevent navigation if a condition is met
• it should not rely on a blocking system modal (window.confirm)...
• ...but it should allow me to use a custom modal
• it should handle the browser back/forward buttons
• it shouldn't pollute the console with errors
• I don't care about handling the page hard refresh or closing the tab (beforeunload). I trust the user knows what s/he is doing and doesn't need to be babysit :)

My solution is based on this old response, it adds support for the browser back/forward buttons, the router basePath and doesn't pollute the console with error logs

It also implements this great suggestion to remove errors in the console.

the custom hook:

import { useRouter } from 'next/router'
import { useCallback, useEffect, useRef } from 'react'

const errorMessage = 'Please ignore this error.'

const throwFakeErrorToFoolNextRouter = () => {
  // Throwing an actual error class trips the Next.JS 500 Page, this string literal does not.
  // eslint-disable-next-line no-throw-literal
  throw errorMessage
}

const rejectionHandler = (event: PromiseRejectionEvent) => {
  if (event.reason === errorMessage) {
    event.preventDefault()
  }
}
interface Props {
  shouldStopNavigation: boolean
  onNavigate: () => void
}

const useNavigationObserver = ({ shouldStopNavigation, onNavigate }: Props) => {
  const router = useRouter()
  const currentPath = router.asPath
  const nextPath = useRef('')
  const navigationConfirmed = useRef(false)

  const killRouterEvent = useCallback(() => {
    router.events.emit('routeChangeError', '', '', { shallow: false })
    throwFakeErrorToFoolNextRouter()
  }, [router])

  useEffect(() => {
    navigationConfirmed.current = false

    const onRouteChange = (url: string) => {
      if (currentPath !== url) {
        // if the user clicked on the browser back button then the url displayed in the browser gets incorrectly updated
        // This is needed to restore the correct url.
        // note: history.pushState does not trigger a page reload
        window.history.pushState(null, '', router.basePath + currentPath)
      }

      if (
        shouldStopNavigation &&
        url !== currentPath &&
        !navigationConfirmed.current
      ) {
        // removing the basePath from the url as it will be added by the router
        nextPath.current = url.replace(router.basePath, '')
        onNavigate()
        killRouterEvent()
      }
    }

    router.events.on('routeChangeStart', onRouteChange)
    window.addEventListener('unhandledrejection', rejectionHandler)

    return () => {
      router.events.off('routeChangeStart', onRouteChange)
      window.removeEventListener('unhandledrejection', rejectionHandler)
    }
  }, [
    currentPath,
    killRouterEvent,
    onNavigate,
    router.basePath,
    router.events,
    shouldStopNavigation,
  ])

  const confirmNavigation = () => {
    navigationConfirmed.current = true
    router.push(nextPath.current)
  }

  return confirmNavigation
}

export { useNavigationObserver }

Usage example:

  // let's assume formDirty is used to toggle the custom hook

  const navigate = useNavigationObserver({
    shouldStopNavigation: formDirty,
    onNavigate: () => {
      setShowModal(true)
    },
  })

... 

// somewhere else if the user confirms s/he wants to leave
navigate();

[koladev32]

Thanks for the solution @cuginoAle

Some points that can help other devs I believe :

• Don't call a router method in the navigate callback. It might cause infinite rendering on the router side, causing issues such as Uncaught (in promise) DOMException: The operation is insecure. next router

[Fleurig]

Thank you so much, this is exactly what I needed!

[cuginoAle]

@koladev32 :
Good point, there's no need to call any router method as onNavigate already does it for us:

router.push(nextPath.current)

[scott-mfv]

It seems that it doesn't work properly when clicking on the forward button. For example, if the history list is page 1, page 2, page 3 and a user is in page 2. If he clicks the forward button, after running your hook, the history list will be page 1, page 2, page 3, page 2.

[ed-peretokin]

I've encountered an unusual behavior that pertains to routing and dynamic navigation when query parameters are involved. Specifically, when the routes aren't limited to page transitions but also include query parameters (e.g., "/register?step=one" or "/register?step=two") and the navigation is managed dynamically using router.push({ query: newQuery }), two issues surface:

• Excessive History Entries: When navigation is prevented due to "unsaved changes," and the user cancels the action, a new entry is added to the browser's history. If this cancellation occurs multiple times (5 or more, for instance), it results in a cluttered history, making it cumbersome to navigate backward.

• Incomplete onRouteChange Callback: When navigation is halted due to "unsaved changes," and the user chooses to leave the page, everything appears to function correctly. However, an issue arises when the user subsequently clicks the "back" button. While the URL is updated to reflect the correct query parameters, the onRouteChange callback is not triggered as expected.

In my experience, the solution that worked for me was to modify the current approach. Instead of:

window.history.pushState(null, '', router.basePath + currentPath)

I found success with the following:

window.history.replaceState(window.history.state, '', router.basePath + currentPath);

This change in the history management method resolved the issues I encountered.

[omerman]

someone has a fix with app directory? 😅

[omerman]

The below code solves AppRouter route cancellation app/ dir

NOT for pages router /pages dir

I got a fix for app directory AppRouter. works like a charm. Posting here for everyone in need.
Compiled this code from many pieces I've seen and also my own experience :)
(p.s It's a clear hack.. but it works and covers all of the use cases I could think of)

1. Block navigation from <a href>
2. Block navigation from popstate (back/forward) - was very hard digging into nextjs code, if you have better solutions Im all ears 😅
3. Block navigation from page refresh / browser close

/// useBeforeUnload.ts
'use client';
import { useRouter } from 'next/navigation';
import { useEffect, useId } from 'react';
import { remove } from 'lodash-es';

let isForceRouting = false;
const activeIds: string[] = [];
let lastKnownHref: string;

export const useBeforeUnload = (isActive = true) => {
  const id = useId();

  // Handle <Link> clicks & onbeforeunload(attemptimg to close/refresh browser)
  useEffect(() => {
    if (!isActive) return;
    lastKnownHref = window.location.href;

    activeIds.push(id);

    const handleAnchorClick = (e: Event) => {
      const targetUrl = (e.currentTarget as HTMLAnchorElement).href,
        currentUrl = window.location.href;

      if (targetUrl !== currentUrl) {
        const res = beforeUnloadFn();
        if (!res) e.preventDefault();
        lastKnownHref = window.location.href;
      }
    };

    let anchorElements: HTMLAnchorElement[] = [];

    const disconnectAnchors = () => {
      anchorElements.forEach((anchor) => {
        anchor.removeEventListener('click', handleAnchorClick);
      });
    };

    const handleMutation = () => {
      disconnectAnchors();

      anchorElements = Array.from(document.querySelectorAll('a[href]'));
      anchorElements.forEach((anchor) => {
        anchor.addEventListener('click', handleAnchorClick);
      });
    };

    const mutationObserver = new MutationObserver(handleMutation);
    mutationObserver.observe(document.body, { childList: true, subtree: true });
    addEventListener('beforeunload', beforeUnloadFn);

    return () => {
      removeEventListener('beforeunload', beforeUnloadFn);
      disconnectAnchors();
      mutationObserver.disconnect();
      remove(activeIds, (x) => x === id);
    };
  }, [isActive, id]);
};

const beforeUnloadFn = (event?: BeforeUnloadEvent) => {
  if (isForceRouting) return true;

  const message = 'Discard unsaved changes?';

  if (event) {
    event.returnValue = message;
    return message;
  } else {
    return confirm(message);
  }
};

const BeforeUnloadProvider = ({ children }: React.PropsWithChildren) => {
  const router = useRouter();
  useEffect(() => {
    lastKnownHref = window.location.href;
  });

  // Hack nextjs13 popstate impl, so it will include route cancellation.
  // This Provider has to be rendered in the layout phase wrapping the page.
  useEffect(() => {
    let nextjsPopStateHandler: (...args: any[]) => void;

    function popStateHandler(...args: any[]) {
      useBeforeUnload.ensureSafeNavigation(
        () => {
          nextjsPopStateHandler(...args);
          lastKnownHref = window.location.href;
        },
        () => {
          router.replace(lastKnownHref, { scroll: false });
        }
      );
    }

    addEventListener('popstate', popStateHandler);
    const originalAddEventListener = window.addEventListener;
    window.addEventListener = (...args: any[]) => {
      if (args[0] === 'popstate') {
        nextjsPopStateHandler = args[1];
        window.addEventListener = originalAddEventListener;
      } else {
        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
        // @ts-ignore
        originalAddEventListener(...args);
      }
    };

    return () => {
      window.addEventListener = originalAddEventListener;
      removeEventListener('popstate', popStateHandler);
    };
  }, []);

  return children;
};

useBeforeUnload.Provider = BeforeUnloadProvider;

useBeforeUnload.forceRoute = async (cb: () => void | Promise<void>) => {
  try {
    isForceRouting = true;
    await cb();
  } finally {
    isForceRouting = false;
  }
};

useBeforeUnload.ensureSafeNavigation = (
  onPerformRoute: () => void,
  onRouteRejected?: () => void
) => {
  if (activeIds.length === 0 || beforeUnloadFn()) {
    onPerformRoute();
  } else {
    onRouteRejected?.();
  }
};

/// layout.tsx  (root layout)
export default function RootLayout({children}: React.PropsWithChildren) {
  return <useBeforeUnload.Provider>{children}</useBeforeUnload.Provider>
}

///SomeFileWithRouteProtection.tsx

// in the render phase somewhere
useBeforeUnload(isFormDirty);

// Example of forceRouting
function saveAndReroute() {
useBeforeUnload.forceRoute(async () => {
   await  save() // If we save and reroute inside save(), we should be able to bypass the route cancellation
});
}

Enjoy

[naphtul]

@omerman, thank you for your elaborate suggestions. Let's jump straight to item 4 on your list. Here's the fresh project I've created. I'd appreciate it if you could spare some time to take a look. Thank you!

[omerman]

Sure I'll be glad to take a look and let you know how it goes :)

[omerman]

@naphtul

Ok, for some reason, next throws this error if we don't already wrap the useBeforeUnload.Provider as part of a client component.

I always have a "use client" main provider that wraps everything and this is why I didnt encounter this.

TBH im not sure why it doesnt work out of the box without the wrapping fix 😅

In any case I forked you repo and added a fix on mine you are welcome to take a look.
I also took my most recent useBeforeUnload code and added it there, you are welcome to check it out.

https://github.com/omerman/next-useBeforeUnload

[naphtul]

Excellent! That works perfectly, thank you.
I have one more question/request in this context:
I would like to do something just before OK is clicked on the "Discard unsaved changes?" message.
Do you mind telling me where in the code that is?
To provide you with context as to why I am asking:
I am using Zustand to keep the temporary changes on the page (a.k.a "dirty") and I want to reset that store once OK is clicked on the discard prompt.
If you have other suggestions, I am all ears.

[omerman]

Im glad to hear it works now 😄
Regarding your question, I think the best approach is something like adding a behavior on the page itself, that once the page is unmounting, call the store reset. something like this:

// Somewhere at the end of hook calls of page.tsx
useEffect(() => {

return () => {
// Since react 18, this code will also run on the page load at dev mode because React triggers `useEffect`s twice uppon first mount
  cleanStore();
}
}, []);

You can also extract this behavior to a custom hook, and use it when needed.

[Taiki92777]

Solved for app/ dir, maybe

Hi, everyone. I think the code below is simple and robust fix.
document.addEventListener('click', handleClick, true) is important. Third parameter capture option should be set to true.
No need to use any provider, just use useBeforeUnload(isConfirm, message)!!
Enjoooooy:)

/// useBeforeUnload.ts
import { useEffect } from 'react'
import { useBeforeUnload as _useBeforeUnload } from 'react-use'

export const useBeforeUnload = (
  isConfirm = true,
  message = 'Are you sure want to leave this page?'
) => {
  // check when page is about to be reloaded
  _useBeforeUnload(isConfirm, message)

  // check when page is about to be changed
  useEffect(() => {
    function isAnchorOfCurrentUrl(currentUrl: string, newUrl: string) {
      const currentUrlObj = new URL(currentUrl)
      const newUrlObj = new URL(newUrl)
      // Compare hostname, pathname, and search parameters
      if (
        currentUrlObj.hostname === newUrlObj.hostname &&
        currentUrlObj.pathname === newUrlObj.pathname &&
        currentUrlObj.search === newUrlObj.search
      ) {
        // Check if the new URL is just an anchor of the current URL page
        const currentHash = currentUrlObj.hash
        const newHash = newUrlObj.hash
        return (
          currentHash !== newHash &&
          currentUrlObj.href.replace(currentHash, '') === newUrlObj.href.replace(newHash, '')
        )
      }
      return false
    }

    function findClosestAnchor(element: HTMLElement | null): HTMLAnchorElement | null {
      while (element && element.tagName.toLowerCase() !== 'a') {
        element = element.parentElement
      }
      return element as HTMLAnchorElement
    }
    function handleClick(event: MouseEvent) {
      try {
        const target = event.target as HTMLElement
        const anchor = findClosestAnchor(target)
        if (anchor) {
          const currentUrl = window.location.href
          const newUrl = (anchor as HTMLAnchorElement).href
          const isAnchor = isAnchorOfCurrentUrl(currentUrl, newUrl)
          const isDownloadLink = (anchor as HTMLAnchorElement).download !== ''

          const isPageLeaving = !(newUrl === currentUrl || isAnchor || isDownloadLink)

          if (isPageLeaving && isConfirm && !window.confirm(message)) {
            // Cancel the route change
            event.preventDefault()
            event.stopPropagation()
          }
        }
      } catch (err) {
        alert(err)
      }
    }

    // Add the global click event listener
    document.addEventListener('click', handleClick, true)

    // Clean up the global click event listener when the component is unmounted
    return () => {
      document.removeEventListener('click', handleClick, true)
    }
  }, [isConfirm, message])
}

How to use

/// YourComponent.tsx
import {useBeforeUnload} from "@/hooks/useBeforeUnload"

function YourComponent () {
  useBeforeUnload(isFormDirty, customMsg)
  return <>...</>
}

[omerman]

@tchtrong
First of all thank you for the feedback! :)

1. If you get a chance to post here the solution for the A->C->C issue you raised it will be awesome
2. If we will avoid using window.addEventListener for 'popstate' up until after the first render, It will always be safe.
   I guess it could get tricky if we add a library that will use it as well, but It's not common for 3rd party libraries to listen on that specific event. Hopefully one day soon nextjs will address this issue 😅

[tchtrong]

Hi @omerman, thank you for your response. After doing my research, I'm afraid that we cannot keep the history in a correct state. When the user click the back or forward button of browser, while we can catch the popstate event, we cannot know which button is pressed (this is a problem that has not been solved and been there for a long time). Therefore we cannot move in the opposite direction to correct the history stack. We can guess by first trying moving forward (or backward), check if the URL is corrected, and then move in the opposite direction if the URL is still incorrect. But still, there is a the problem when there is a cross-origin domain in the history stack, which triggers the beforeunload event and messes up our flow. So I guess what we can do best is to ask user whether they want to save the changes or not, and proceed to navigate either way (or you can try the new Navigation API to see if it work).

[yutafukuchi-1015]

Is it possible to have a custom dialog instead of a window.confirm?
window.addEventListener can not wait async ?

[omerman]

@yutafukuchi-1015 It's not possible for native browser events such as backward/forward/refresh.
All other ways of navigation, yes it's possible

[damoahdominic]

Thanks so much. I had a simple useCase and it worked perfectly. You are a legend for this solution.