[next/navigation] Next 13: useRouter events?

[waltergalvao]

It seems the new useRouter implementation does not expose events.

Is support for events planned?

https://beta.nextjs.org/docs/app-directory-roadmap#planned-features
Would "Intercepting Routes" here mean events?

[icyJoseph]

Not sure it means events though... #41745 (reply in thread)

Because of concurrent rendering router.events doesn't make sense anymore as any navigation can be canceled without a way to detect that happening.

The way to listen for page changes would be something like this:

'use client'
import {usePathname, useSearchParams} from 'next/navigation'

function useNavigationEvent() {
   const pathname = usePathname()
  const searchParams = useSearchParams()
   useEffect(() => {
      const url = pathname + searchParams.toString()
      sendSomewhere(url)
   }, [pathname, searchParams])
}

[thelonewolf123]

Hey @naeem-qv

you can create a wrapper for <Link/>, and use onClick and unmount event to track the route change start and route change end. for useRouter() hook, you can create a custom hook and add a proxy to the router object to track the .push and .back invocation and use it as a trigger for route change start.

'use client'

import Link from 'next/link'
import { PropsWithChildren, useEffect } from 'react'
import NProgress from 'nprogress'
import 'nprogress/nprogress.css'

export const CustomLink: React.FC<PropsWithChildren<{ href: string }>> = ({
    href,
    children
}) => {
    useEffect(() => {
        return () => {
            NProgress.done()
        }
    }, [])

    return (
        <>
            <Link href={href} onClick={() => NProgress.start()}>
                {children}
            </Link>
        </>
    )
}

I hope this helps.

[Fox32]

This is actually a bit more tricky. Take care to handle the right keyboard modifiers in the onClick handler. If a user opens a link in a new tab by pressing a key on click, you might not want to start the loading animation.

[dstarosta]

The progress is not going to stop if the href is the same as the current relative URL. You would need a check in the onClick event handler similar to

    if (href === window.location.href.replace(window.location.origin, '')) {
      return;
    }

[NK3678]

Please provide the code to handle it " If a user opens a link in a new tab by pressing a key on click, you might not want to start the loading animation."

[iamsabbirsobhani]

Now its working as indented

"use client";
import Link from 'next/link';
import { PropsWithChildren, useEffect } from 'react';
import NProgress from 'nprogress';
import 'nprogress/nprogress.css';

export const Linkn: React.FC<PropsWithChildren<{ href: string }>> = ({
  href,
  children,
}) => {
  useEffect(() => {
    return () => {
      NProgress.done();
    };
  }, []);

  const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
    if (shouldStartAnimation(e)) {
      NProgress.start();
    }
  };

  const handleKeyDown = (e: React.KeyboardEvent<HTMLAnchorElement>) => {
    if (shouldStartAnimation(e)) {
      NProgress.start();
    }
  };

  const shouldStartAnimation = (
    e:
      | React.MouseEvent<HTMLAnchorElement>
      | React.KeyboardEvent<HTMLAnchorElement>,
  ): boolean => {
    // Check if it's a left mouse click without any keyboard modifiers
    if (
      (e as React.MouseEvent<HTMLAnchorElement>).button === 0 &&
      !(e as React.MouseEvent<HTMLAnchorElement>).ctrlKey &&
      !(e as React.MouseEvent<HTMLAnchorElement>).shiftKey &&
      !(e as React.MouseEvent<HTMLAnchorElement>).metaKey
    ) {
      // Get the current pathname from window.location
      const currentPathname = window.location.pathname;

      // Check if the link's href is the same as the current pathname
      if (href === currentPathname) {
        return false; // Don't start the animation for same route links
      }

      return true;
    }

    // Check for middle mouse button click
    if ((e as React.MouseEvent<HTMLAnchorElement>).button === 1) {
      return false;
    }

    // Check for right mouse button click
    if ((e as React.MouseEvent<HTMLAnchorElement>).button === 2) {
      return false;
    }

    // Check if it's an accessibility event (e.g., screen reader activation)
    if (
      e.type === 'click' &&
      (e as React.MouseEvent<HTMLAnchorElement>).detail === 0
    ) {
      return true;
    }

    return false;
  };

  return (
    <Link href={href} legacyBehavior>
      <a
        onClick={handleClick}
        onKeyDown={handleKeyDown}
        tabIndex={0} // Ensure the link is keyboard focusable
      >
        {children}
      </a>
    </Link>
  );
};

[garrettparris]

looking for event functionality aswell.

[tinnohofficial]

Please add route events.

[petedegraw]

...and maybe extend the browser APIs rather than break them. Please :)

[pbs-jmo]

Same. Switching to App Router is a bit weird so far because I've not yet found a way to replicate this feature.

[a95tbirdsc]

How is "pathname" and "searchParams" being used in the statement below. Just trying to understand the code.

Returning those variables?

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

useEffect(() => {
const url = pathname + searchParams.toString()
sendSomewhere(url)
}, [pathname, searchParams])

I've also seen this:

useEffect(() => {
const url = pathname + searchParams.toString()
sendSomewhere(url)
}, [ ])

Trying to understand the differences between the two statements.

[joe-pellegrino]

The dependency array [pathname, searchParams] means that the function will execute on render as well as when any one of those values changes.

[a95tbirdsc]

Thank you.

[stevenlafl]

I spent a few hours of scouring the internet for a way to do this. Then a few to build this. Very annoying. Here's my best attempt at a solution. No idea if it's the right approach. It's probably not right for everyone, but if it's right for you, great!

You can instead of the below just use https://www.npmjs.com/package/nextjs13-router-events I published for this reason and follow those instructions.

---

Link.tsx

"use client";

import NextLink from "next/link";
import { forwardRef, useContext } from "react";
import { useRouteChangeContext } from "./RouteChangeProvider";

// https://github.com/vercel/next.js/blob/400ccf7b1c802c94127d8d8e0d5e9bdf9aab270c/packages/next/src/client/link.tsx#L169
function isModifiedEvent(event: React.MouseEvent): boolean {
  const eventTarget = event.currentTarget as HTMLAnchorElement | SVGAElement;
  const target = eventTarget.getAttribute("target");
  return (
    (target && target !== "_self") ||
    event.metaKey ||
    event.ctrlKey ||
    event.shiftKey ||
    event.altKey || // triggers resource download
    (event.nativeEvent && event.nativeEvent.button === 2)
  );
}

const Link = forwardRef<HTMLAnchorElement, React.ComponentProps<"a">>(function Link(
  { href, onClick, ...rest },
  ref,
) {
  const useLink = href && href.startsWith("/");
  if (!useLink) return <a href={href} onClick={onClick} {...rest} />;

  const { onRouteChangeStart } = useRouteChangeContext();

  return (
    <NextLink
      href={href}
      onClick={(event) => {
        if (!isModifiedEvent(event)) {
          const { pathname, search, hash } = window.location;
          const hrefCurrent = `${pathname}${search}${hash}`;
          const hrefTarget = href as string;
          if (hrefTarget !== hrefCurrent) {
            onRouteChangeStart();
          }
        }
        if (onClick) onClick(event);
      }}
      {...rest}
      ref={ref}
    />
  );
});

export default Link;

RouteChangeProvider.tsx

import { usePathname, useSearchParams } from 'next/navigation';
import { createContext, useContext, useState, useCallback, Suspense, useEffect } from 'react';

/** Types */
type RouteChangeContextProps = {
  routeChangeStartCallbacks: Function[];
  routeChangeCompleteCallbacks: Function[];
  onRouteChangeStart: () => void;
  onRouteChangeComplete: () => void;
};

type RouteChangeProviderProps = {
  children: React.ReactNode
};

/** Logic */

const RouteChangeContext = createContext<RouteChangeContextProps>(
  {} as RouteChangeContextProps
);

export const useRouteChangeContext = () => useContext(RouteChangeContext);

function RouteChangeComplete() {
  const { onRouteChangeComplete } = useRouteChangeContext();
  
  const pathname = usePathname();
  const searchParams = useSearchParams();
  useEffect(() => onRouteChangeComplete(), [pathname, searchParams]);

  return null;
}

export const RouteChangeProvider: React.FC<RouteChangeProviderProps> = ({ children }: RouteChangeProviderProps) => {
  const [routeChangeStartCallbacks, setRouteChangeStartCallbacks] = useState<Function[]>([]);
  const [routeChangeCompleteCallbacks, setRouteChangeCompleteCallbacks] = useState<Function[]>([]);
  
  const onRouteChangeStart = useCallback(() => {
    routeChangeStartCallbacks.forEach((callback) => callback());
  }, [routeChangeStartCallbacks]);

  const onRouteChangeComplete = useCallback(() => {
    routeChangeCompleteCallbacks.forEach((callback) => callback());
  }, [routeChangeCompleteCallbacks]);
  
  return (
    <RouteChangeContext.Provider
      value={{
        routeChangeStartCallbacks,
        routeChangeCompleteCallbacks,
        onRouteChangeStart,
        onRouteChangeComplete
      }}
    >
      {children}
      <Suspense>
        <RouteChangeComplete />
      </Suspense>
    </RouteChangeContext.Provider>
  );
};

useRouteChange.tsx

import { useEffect } from 'react';
import { useRouteChangeContext } from './RouteChangeProvider';

type CallbackOptions = {
  onRouteChangeStart?: Function;
  onRouteChangeComplete?: Function;
}

const useRouteChange = (options: CallbackOptions) => {
  const { routeChangeStartCallbacks, routeChangeCompleteCallbacks } = useRouteChangeContext();
  
  useEffect(() => {
    // add callback to the list of callbacks and persist it
    if (options.onRouteChangeStart) {
      routeChangeStartCallbacks.push(options.onRouteChangeStart);
    }
    if (options.onRouteChangeComplete) {
      routeChangeCompleteCallbacks.push(options.onRouteChangeComplete);
    }

    return () => {
      // Find the callback in the array and remove it.
      if (options.onRouteChangeStart) {
        const index = routeChangeStartCallbacks.indexOf(options.onRouteChangeStart);
        if (index > -1) {
          routeChangeStartCallbacks.splice(index, 1);
        }
      }
      if (options.onRouteChangeComplete) {
        const index = routeChangeCompleteCallbacks.indexOf(options.onRouteChangeComplete);
        if (index > -1) {
          routeChangeCompleteCallbacks.splice(index, 1);
        }
      }
    };
  }, [options, routeChangeStartCallbacks, routeChangeCompleteCallbacks]);
};

export default useRouteChange;

Then use like this:

Replace regular NextJS Link components with this one:

import { Link } from './Link';

That Link component should be compatible with your setup.

Your layout.tsx:

import { RouteChangeProvider } from './RouteChangeProvider';
...
return (
  <RouteChangeProvider>
    {children}
  </RouteChangeProvider>
)

Your component, where you want to monitor the onRouteChangeStart and onRouteChangeComplete events:

import useRouteChange from './useRouteChange';
...
export default function Component(props: any) {
  ...
  useRouteChange({
    onRouteChangeStart: () => {
      console.log('onStart 3');
    },
    onRouteChangeComplete: () => {
      console.log('onComplete 3');
    }
  });
  ...
}

[saeideh-abs]

could you please give an example of how we should use it? it seems onRouteChangeStart is not working. I can not see "onStart 3" in my console

[stevenlafl]

@saeideh-abs Use the Link component above instead of the standard Link component. On clicking it, you should see it.

[aminrms]

It is suitable for routing with useRouter from "router/navigation"?

[tinnohofficial]

Thank you. I appreciate it. I am gonna follow up on the code implementation. Yours truly, Augustino M.

…

On Sun, Jul 16, 2023, 1:08 PM Steven Linn ***@***.***> wrote: I spent a few hours of scouring the internet for a way to do this. Then a few to build this. Very annoying. Here's my best attempt at a solution. No idea if it's the right approach. It's probably not right for everyone, but if it's right for you, great! You can instead of the below just use https://www.npmjs.com/package/nextjs13-router-events I published for this reason and follow those instructions. ------------------------------ *Link.tsx* "use client"; import NextLink from "next/link";import { forwardRef, useContext } from "react";import { useRouteChangeContext } from "./RouteChangeProvider"; // https://github.com/vercel/next.js/blob/400ccf7b1c802c94127d8d8e0d5e9bdf9aab270c/packages/next/src/client/link.tsx#L169function isModifiedEvent(event: React.MouseEvent): boolean { const eventTarget = event.currentTarget as HTMLAnchorElement | SVGAElement; const target = eventTarget.getAttribute("target"); return ( (target && target !== "_self") || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || // triggers resource download (event.nativeEvent && event.nativeEvent.button === 2) );} const Link = forwardRef<HTMLAnchorElement, React.ComponentProps<"a">>(function Link( { href, onClick, ...rest }, ref,) { const useLink = href && href.startsWith("/"); if (!useLink) return <a href={href} onClick={onClick} {...rest} />; const { onRouteChangeStart } = useRouteChangeContext(); return ( <NextLink href={href} onClick={(event) => { if (!isModifiedEvent(event)) { const { pathname, search, hash } = window.location; const hrefCurrent = `${pathname}${search}${hash}`; const hrefTarget = href as string; if (hrefTarget !== hrefCurrent) { onRouteChangeStart(); } } if (onClick) onClick(event); }} {...rest} ref={ref} /> );}); export default Link; *RouteChangeProvider.tsx* import { usePathname, useSearchParams } from 'next/navigation';import { createContext, useContext, useState, useCallback, Suspense, useEffect } from 'react'; /** Types */type RouteChangeContextProps = { routeChangeStartCallbacks: Function[]; routeChangeCompleteCallbacks: Function[]; onRouteChangeStart: () => void; onRouteChangeComplete: () => void;}; type RouteChangeProviderProps = { children: React.ReactNode}; /** Logic */ const RouteChangeContext = createContext<RouteChangeContextProps>( {} as RouteChangeContextProps); export const useRouteChangeContext = () => useContext(RouteChangeContext); function RouteChangeComplete() { const { onRouteChangeComplete } = useRouteChangeContext(); const pathname = usePathname(); const searchParams = useSearchParams(); useEffect(() => onRouteChangeComplete(), [pathname, searchParams]); return null;} export const RouteChangeProvider: React.FC<RouteChangeProviderProps> = ({ children }: RouteChangeProviderProps) => { const [routeChangeStartCallbacks, setRouteChangeStartCallbacks] = useState<Function[]>([]); const [routeChangeCompleteCallbacks, setRouteChangeCompleteCallbacks] = useState<Function[]>([]); const onRouteChangeStart = useCallback(() => { routeChangeStartCallbacks.forEach((callback) => callback()); }, [routeChangeStartCallbacks]); const onRouteChangeComplete = useCallback(() => { routeChangeCompleteCallbacks.forEach((callback) => callback()); }, [routeChangeCompleteCallbacks]); return ( <RouteChangeContext.Provider value={{ routeChangeStartCallbacks, routeChangeCompleteCallbacks, onRouteChangeStart, onRouteChangeComplete }} > {children} <Suspense> <RouteChangeComplete /> </Suspense> </RouteChangeContext.Provider> );}; *useRouteChange.tsx* import { useEffect } from 'react';import { useRouteChangeContext } from './RouteChangeProvider'; type CallbackOptions = { onRouteChangeStart?: Function; onRouteChangeComplete?: Function;} const useRouteChange = (options: CallbackOptions) => { const { routeChangeStartCallbacks, routeChangeCompleteCallbacks } = useRouteChangeContext(); useEffect(() => { // add callback to the list of callbacks and persist it if (options.onRouteChangeStart) { routeChangeStartCallbacks.push(options.onRouteChangeStart); } if (options.onRouteChangeComplete) { routeChangeCompleteCallbacks.push(options.onRouteChangeComplete); } return () => { // Find the callback in the array and remove it. if (options.onRouteChangeStart) { const index = routeChangeStartCallbacks.indexOf(options.onRouteChangeStart); if (index > -1) { routeChangeStartCallbacks.splice(index, 1); } } if (options.onRouteChangeComplete) { const index = routeChangeCompleteCallbacks.indexOf(options.onRouteChangeComplete); if (index > -1) { routeChangeCompleteCallbacks.splice(index, 1); } } }; }, [options, routeChangeStartCallbacks, routeChangeCompleteCallbacks]);}; export default useRouteChange; Then use like this: Replace regular NextJS Link components with this one: import { Link } from './Link'; That Link component should be compatible with your setup. Your layout.tsx: import { RouteChangeProvider } from './RouteChangeProvider'; ...return ( <RouteChangeProvider> {children} </RouteChangeProvider>) Your component, where you want to monitor the onRouteChangeStart and onRouteChangeComplete events: import useRouteChange from './useRouteChange'; ...export default function Component(props: any) { ... useRouteChange({ onRouteChangeStart: () => { console.log('onStart 3'); }, onRouteChangeComplete: () => { console.log('onComplete 3'); } }); ...} — Reply to this email directly, view it on GitHub <#41934 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AK7QDGWZFJSYXGE3OBZRS4DXQO4S5ANCNFSM6AAAAAARPUBUTE> . You are receiving this because you commented.Message ID: <vercel/next. ***@***.***>

[pfischer1290]

also, there is still no possibility to stop a route change event as there was with the page router, correct?
very annoying and breaks the use case of preventing a user to accidentally navigate away from a partially filled form, for example.

or does anybody have a solution to this use case with nextjs app router?

i tried everything possible already.
see this discord thread for reference: https://discord.com/channels/752553802359505017/1119298354288013322

[pfischer1290]

no... i think there is no possibility until there is no support by the app router... maybe any maintainer could give an update?

[fdev]

I need route change blocking for the exact same reason.

[neilpoulin]

I literally just converted an old app to Next 14 with one of the big new features planned was preventing navigation away from un-saved forms... and now I find out it's not even possible with the latest stack (but was in the now-legacy pages directory).

I did get it working by moving the page(s) that need the beforeunload hooks into the pages directory and have everything else in the app directory, but this has some major drawbacks, namely that navigating between the app and pages directory looses all app context, since it is no longer working as a Single Page App. Meaning, I have to re-load my data (using SWR), and re-auth, which is very slow. So much so that I had to scrap it.

Very disappointing.

[fabb]

Oh no, I'm in the progress of migrating an app and I need to migrate exactly this feature. Yay.

[SalahAdDin]

Anyway to ask to Vercel team on working on this issue?

[myskotima130]

Any updates about possibility to block route change?

[pfischer1290]

bump. is there any maintainer sticking around here?

[smyja]

next13 is definitely not production ready.

[Fiontan]

But it's getting there rapidly with obvious improvements each release it must be said.

[iamsabbirsobhani]

Agreed, router event is an important functionality for an app. It should have been prioritized in the first place.

[paulm17]

Hopefully Next14 will have some improvements? 🤔

[samuhmatos]

next 14 appearing in 2050 lol

[neilpoulin]

it's here now and no improvements in terms of the router

[SalahAdDin]

NO improvement yet.

[hvitis]

I am also confused when it comes to the events or documentation changes between function versions (I have a legacy app to maintain)

[melodyclue]

Are there any alternative solutions?

[samuhmatos]

I am working in a package able to change route using events to make the load animation. https://www.npmjs.com/package/nextjs-progressloader

[praveennagaraj97]

@samuhmatos Doesn't work when page is navigated using router.push()!

[samuhmatos]

To invoke a route with progress bar animation, use the function changeRoute() instead router.push().
I hight recommend you read the documentation to see about Container and changeRoute()
see: https://github.com/samuhmatos/nextjs-progressloader#advanced-usage

[raulbarriga]

Needed router.events.on() for a loading progress bar.

[samuhmatos]

For everyone who want to make loading animation when change route, i am working in a package able to replace the useRouter() WITHOUT LOSING THE PREFETCH NEXT FEATURE
https://www.npmjs.com/package/nextjs-progressloader

[melodyclue]

Is it possible to implement only those screens where router events are required in the pages directory?
What I want to do is to control the user leaving the screen when their input is not saved in the middle of a page.

[samuhmatos]

You can add whatever route you would need. Everything you have to do is create a ContainerLink, but make sure where you're creating the container to be available where you need!

[reo-yamashita]

I think router.events is needed to prevent users leaving while typing, why did the team remove it? Does anyone know why?

[MarcoBeyer]

I rolled back to the pages router because I couldn't prevent useres from leaving page without saving.

[reo-yamashita]

If I want to do that, is it best to use the pages directory at the moment and be prepared to move to the app router at any time?

[samuhmatos]

I think thy want we doing our own system navigation. Have sense? No, bu to Vercel has!

[pfischer1290]

thats exactly the functionality what we are missing. it is impossible to implement with the app router :(

[samuhmatos]

I am trying to find in the releases notes if they explained to the community, but still nothing.

[Lamperoyge]

For us we needed to persist a specific query param across all route changes and instead of sending it via each router push or Link navigation this is what worked for us. Then you can import it in the layouts

'use client';

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

const RouteListener = () => {
  const searchParams = useSearchParams();
  const externalId = searchParams.get('ext_id');
  const pathname = usePathname();
  const ref = useRef(null);

  useEffect(() => {
    const storedExternalId = externalId || localStorage.getItem('externalId');
    if (externalId) {
      localStorage.setItem('externalId', externalId);
    }
    ref.current = storedExternalId ?? null;
  }, []);

  useEffect(() => {
    const externalId = ref.current;
    const params = new URLSearchParams(searchParams.toString());
    externalId && params.set('ext_id', externalId);
    window.history.pushState(null, '', `?${params.toString()}`);
  }, [pathname]);

  return null;
};

export default RouteListener;

[arshad-yaseen]

@leerob @leerob @leerob

Can we reintroduce router events, please? I need to display a top-loader during router changes, so we need the route change start and end events.

[bilalmohib]

@leerob Please can you add router events for NextJS if this package is able to use Router events please can you add to core NextJS
: https://github.com/joulev/nextjs13-appdir-router-events

@leerob I can assure you that We need NextJS router events any way.

There is no other suitable alternative for that. Please add this to native NextJS Library

[SalahAdDin]

It seems the new useRouter implementation does not expose events.

Is support for events planned?

https://beta.nextjs.org/docs/app-directory-roadmap#planned-features Would "Intercepting Routes" here mean events?

The page no longer redirects to the road map, and it has been a long time to see such interceptors...

[jdevcc]

Hi everyone, if you're looking to add a progress bar in the app dir, this blog post is helpful: https://buildui.com/posts/global-progress-in-nextjs

Just to be clear - creating a wrapper around the Link component that reimplements router navigation is a hacky solution in my book. I believe Next.js should expose a boolean for pending navigations. More in my previous comment.

[arshad-yaseen]

This isn't a good solution for a really big project. They use their own way to change pages and have their own kind of Link thing.

[jdevcc]

Correct - this is why I added the note at the bottom. But this may help some people while we're waiting for a Next.js-supported solution.

[leerob]

Hey everyone, I appreciate your patience here while we worked on a reply. Thanks for answering some of the questions I asked as it helped us collect a list of current solutions. Please let us know if this helps!

Current Solutions

Displaying a progress indicator while a route transition is happening

All navigations in the Next.js App Router are built on React Transitions. This means you can use the useTransition hook and use the isPending flag to understand if a transition is currently in-flight. For example:

'use client';

import { useTransition } from 'react';
import NextLink from 'next/link';
import { useRouter } from 'next/navigation';

/**
 * A custom Link component that wraps Next.js's next/link component.
 */
export function Link({
  href,
  children,
  replace,
  ...rest
}: Parameters<typeof NextLink>[0]) {
  const router = useRouter();
  const [isPending, startTransition] = useTransition();

  if (isPending) {
    return <>Pending navigation</>;
  }

  return (
    <NextLink
      href={href}
      onClick={(e) => {
        e.preventDefault();
        startTransition(() => {
          const url = href.toString();
          if (replace) {
            router.replace(url);
          } else {
            router.push(url);
          }
        });
      }}
      {...rest}
    >
      {children}
    </NextLink>
  );
}

We’re also going to work on a proposal for a pending property on next/link to make this type of UI easier specifically for next/link.

There is also a new library called react-transition-progress built by Tim and other React community members to show a nprogress type loading bar while a React Transition runs. It has published next/link bindings, meaning that you can start using the published Link component instead of having to add the startTransition manually.

CleanShot.2024-04-03.at.07.46.09.mp4

It can also be used to show a progress bar when calling other React Transitions like Server Actions and the action property.

View an example deployment.

Shallow routing

In Next.js 14.1 we’ve introduced support for navigating similar to “shallow routing” in Pages Router by using window.history.pushState or window.history.replaceState.

Integrating with analytics libraries or similar tools that need to listen for different routing changes and report back to the service

For analytics, we’re investigating if a proposal similar to useReportWebVitals() that you can pass a function to that runs anytime the URL changes makes sense.

It would look similar to the following example, which you can start using today:

// lib/use-report-analytics.ts

import 'client-only';
import { useEffect } from 'react';
import { usePathname, useSearchParams } from 'next/navigation';

export function useReportAnalytics(reportAnalyticsFn: (url: string) => void) {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  useEffect(() => {
    const url = `${pathname}?${searchParams}`;
    reportAnalyticsFn(url);
  }, [pathname, searchParams]);
}

Preventing navigation away with unsaved changes and show a confirmation model

For blocking the navigations, we’re going to investigate if there is a built-in approach that works for most use-cases. For example, you don’t want to prevent all React Transitions, because that means you can’t submit the form anymore (as that is a React Transition, too).

If you only want to block navigations using e.g. next/link you can take a similar approach as react-transition-progress by lifting up the state and preventing navigation in a custom component:

// components/navigation-block.tsx
'use client';

import {
  Dispatch,
  SetStateAction,
  createContext,
  useContext,
  useEffect,
  useState,
} from 'react';

const NavigationBlockerContext = createContext<
  [isBlocked: boolean, setBlocked: Dispatch<SetStateAction<boolean>>]
>([false, () => {}]);

export function NavigationBlockerProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  // [isBlocked, setBlocked]
  const state = useState(false);
  return (
    <NavigationBlockerContext.Provider value={state}>
      {children}
    </NavigationBlockerContext.Provider>
  );
}

export function useIsBlocked() {
  const [isBlocked] = useContext(NavigationBlockerContext);
  return isBlocked;
}

export function Blocker() {
  const [isBlocked, setBlocked] = useContext(NavigationBlockerContext);
  useEffect(() => {
    setBlocked(() => {
      return true;
    });
    return () => {
      setBlocked(() => {
        return false;
      });
    };
  }, [isBlocked, setBlocked]);
  return null;
}

export function BlockBrowserNavigation() {
  const isBlocked = useIsBlocked();
  useEffect(() => {
    console.log({ isBlocked });
    if (isBlocked) {
      const showModal = (event: BeforeUnloadEvent) => {
        event.preventDefault();
      };

      window.addEventListener('beforeunload', showModal);
      return () => {
        window.removeEventListener('beforeunload', showModal);
      };
    }
  }, [isBlocked]);

  return null;
}

// components/link.tsx

'use client';
import { startTransition } from 'react';
import NextLink from 'next/link';
import { useRouter } from 'next/navigation';
import { useIsBlocked } from './navigation-block';

/**
 * A custom Link component that wraps Next.js's next/link component.
 */
export function Link({
  href,
  children,
  replace,
  ...rest
}: Parameters<typeof NextLink>[0]) {
  const router = useRouter();
  const isBlocked = useIsBlocked();

  return (
    <NextLink
      href={href}
      onClick={(e) => {
        e.preventDefault();

        // Cancel navigation
        if (isBlocked && !window.confirm('Do you really want to leave?')) {
          return;
        }

        startTransition(() => {
          const url = href.toString();
          if (replace) {
            router.replace(url);
          } else {
            router.push(url);
          }
        });
      }}
      {...rest}
    >
      {children}
    </NextLink>
  );
}

// components/form.tsx
import { Blocker } from './navigation-block';

export default function Form() {
  return (
    <>
      <Blocker />
      <input type="text" name="firstname" />
      <input type="text" name="lastname" />
    </>
  );
}

// app/layout.tsx
import {
  BlockBrowserNavigation,
  NavigationBlockerProvider,
} from '@/components/navigation-block';

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>
        <NavigationBlockerProvider>
          {/* Blocks reloading the page / navigating away to other urls */}
          {/* <BlockBrowserNavigation /> */}
          {children}
        </NavigationBlockerProvider>
      </body>
    </html>
  );
}

Then use it when the form has been edited, for example with react-hook-form:

// components/form.tsx
import { useForm, useFormState } from 'react-hook-form';
import { Blocker } from './navigation-block';

function BlockerWhenDirty({
  control,
}: {
  control: ReturnType<typeof useForm>['control'];
}) {
  const { dirtyFields } = useFormState({
    control,
  });

  return Object.keys(dirtyFields).length > 0 ? <Blocker /> : null;
}

View an example deployment.

It’s worth mentioning there’s no browser behavior to prevent popstate (back or forward navigations), so there isn’t a way to add that to the router.

Conclusion

We know the the transition from the Pages Router to the App Router, even when taken incrementally, can create questions about how to use features or APIs the previous router supported, but look different in the new world.

Thank you all for the feedback and patience here. We encourage you all to share solutions you’ve found for your own applications. And if the provided solutions above are working well for you all, we’ll work on moving these to the official documentation.

[Santiago-j-s]

Hi @leerob, tysm for all the information!

Have you had a chance to check out my previous question?

I'm curious to find out if there's a way to incorporate that behavior into the app, ty!

[SalahAdDin]

@skolodyazhnyy There’s no browser behavior to prevent popstate (back or forward navigations), so there isn’t a way to add that to the router.

@jdevcc We are considering adding some of these into Next.js! I mentioned a few options in the post we're investigating. But this gives you all solutions immediately before things are built-in.

Is there any ETA for this behavior?

[josephlodero]

How about saving the data before the user leave or change the router? like saving the current time of the video.

[sriechersrc]

const url = href.toString(); does not work and evaluates to "[object object]". However there is a solution using resolveHref, discussed in this post #22025 (comment)
Btw resolveHref should really be exported as an official utility

[dmitri-gb]

All navigations in the Next.js App Router are built on React Transitions. This means you can use the useTransition hook and use the isPending flag to understand if a transition is currently in-flight.

One major shortcoming of this approach is that it doesn't work with back/forward navigation (popstate). This can be observed on the demo page of the aforementioned react-transition-progress library (click "Go to slow page" → click "Go to home page" → reload (to clear the router cache) → go back — the slow page will load without any loading indicator).

I think you need to keep this in mind when you say...

We’re also going to work on a proposal for a pending property on next/link to make this type of UI easier specifically for next/link.

... as I doubt people want integration with the Link component specifically, rather they want it to work with all ways of navigation.

Also, manually wrapping all links and router.push calls is definitely tedious and it feels like there should be a simpler (built-in) approach when all I want is a loading animation for navigations.

[RickyRoller]

I'd like to propose a different solution, other than taking every interaction point of application code -> App Router and manually tracking the state of the router transition.

The router already uses startTransition internally. A simple change to instead utilize useTransition and make the pending flag available would account for a vast majority of the use cases we you just need to know if a routing transition has started.
Something along these lines RickyRoller@a3cbe12

I agree that we can use the pathname/params to know when the router change has completed, but we still need a realistic way to know when a router change has started.

I can't imagine the change is quite as simple as the commit I linked above, but isn't this a more reasonable direction to go in?

[jorgesandoval-irys]

If there an ETA solution for the popState when user goes back in the broswer button?

[leerob]

There’s no browser behavior to prevent popstate (back or forward navigations), so there isn’t a way to add that to the router.

[sovetski]

Just, WHY? It was working as well with pages router, why it is removed from app router? There are a ton of message here and other topics. With app router we have a lot of problems like that, should we roll back to pages router?

[leerob]

You can use the solutions provided in my comment to implement a prompt when navigating away from unsaved forms. I am sorry that it is not the exact same solution as the Pages Router. It is a different underlying architecture and also has a different API design. Note that the Pages Router still exists, is supported, and has new improvements landing - so if you prefer to use it for your use case, that is okay too.

[SalahAdDin]

What's the point of keeping updating the old Pages API when you just released the App API? Why lose time on deprecated API instead of improving the new one?

[eiskalteschatten]

That's exactly what I've been wondering... It would be interesting to know when the old Pages Router will be deprecated because I can't imagine it's very sustainable to maintain both APIs.

[leerob]

Pages Router is not deprecated @SalahAdDin. It's going to be around for a long time. There will be plenty of communications and heads up in years to come.

[SalahAdDin]

Why APP folder API then?

[garrettparris]

I have nothing to add but Ive been getting emails about this issue for months by now. @leerob in the trenches on this one, love to see it.

[kcrwfrd]

@leerob why can't routeChangeStart and routeChangeComplete events be added to the app router? I've read and re-read this thread and still do not understand why.

[leerob]

Because all navigations in the Next.js App Router are built on React Transitions. There are hooks to observe transitions (as shown above). We might expose a way to observe the Next.js internal transitions, as @RickyRoller suggested.

[kcrwfrd]

Thanks for the response, Lee. Unfortunately the approach of wrapping next/link with your own useTransition call is incomplete, because it doesn't cover popstate navigations.

Exposing the isPending from useTransition would be a decent improvement...but having events is just really handy, for a number of different use-cases.

Is useEffect(() => { ... }, [pathName, searchParams]) effectively a route change completed event? Or is that effect going to fire at the start of a route change?

As an aside, I guess I found a hint to the longer answer of why events were removed in the useTransition docs: the app router is built on React Transitions in order to support Suspense, and React doesn't provide some kind of callback to know when a transition has completed so that you can emit an event for routeChangeComplete... is that right?

FWIW I think the community would appreciate the deeper technical explanation on why events were removed, and whether they will (or may) eventually be added back.

[zacharyliu]

For the use case of showing a global progress indicator during route transitions, we came up with this hack that hooks directly into the router state. This builds on the idea of wrapping calls to the router in useTransition, but works with the regular Link component.

Major caveats:

• This only works in the App Router and fails to build in the Pages Router
• It also only seems to work within a next/dynamic-loaded component, something about the internal import doesn't work server-side.

import { useContext, useEffect, useTransition } from "react";
import { ActionQueueContext } from "next/dist/shared/lib/router/action-queue";

const useIsRouterPending = () => {
  const actionQueue = useContext(ActionQueueContext);
  const [isPending, startTransition] = useTransition();

  useEffect(() => {
    if (!actionQueue) {
      return undefined;
    }
    const originalDispatch = actionQueue.dispatch;
    actionQueue.dispatch = (...args) => {
      startTransition(() => {
        originalDispatch.apply(actionQueue, args);
      });
    };
    return () => {
      actionQueue.dispatch = originalDispatch;
    };
  }, [actionQueue]);

  return isPending;
};

Of course this could break at any time since it's patching an internal API.

[jan0991]

Thanks, this works as expected, but I keep getting: Error: Cannot find module 'react-server-dom-webpack/client.edge' anybody getting the same or any ideas how to fix it?

[mycolaos]

useEffect isn't really an alternative to event handling. It runs after the React tree render and is not under immediate developer control. Events should be dispatched asap to allow immediate actions.

In my use case:
Updating a Jotai atom with Next Router params using the suggested useEffect solution results in at least two rendering cycles:

1. One when Router hooks trigger the re-render.
2. Second when the useEffect is called (after the 1st re-render finishes).

This makes the update visually slow. I would prefer to update my state asap, not when useEffect runs.

With events, I could subscribe to them and update my atoms directly, refreshing my components immediately with new data.

A solution I see is subscribing to window events. In that case, is there a helper to extract dynamic slug params?

[kcrwfrd]

I'm not aware of any window events that will solve this for you. There's only popstate for browser back/forward navigations, or hashchange.

I think you may be able to monkey-patch pushState and replaceState, along with an event listener for popstate, to achieve a routeChangeStart event. Next.js monkey patches the pushState / replaceState methods itself, so I haven't tested if there would be any conflict. I think it should work.

This StackOverflow answer suggests using MutationObserver but I haven't tested it.

There is an upcoming Navigation API that will finally give us a navigate event to accomplish this, but it is not available yet.

[mycolaos]

Yes, I considered all this options, but not MutationObserver, which is strange, since it's purpose is observe DOM changes.

I discarded the monkey patch, since a query change can occurs by different means, not only by pushing.

✅ Current solution
At the end, I decided to sync my atoms by using setTimeout, instead of useEffect, the reasoning is:

• setTimeout is necessary so atoms internal setState is not called while rendering the component that "listens" for router changes.
• Atoms are updated faster than with useEffect.
• Technically doing this shouldn't be a problem, since it simulates updating an atom with an async handler, for example when fetching data.

It would be better to have the real events, though.

[kcrwfrd]

I discarded the monkey patch, since a query change can occurs by different means, not only by pushing.

How else can a query arg change?

I'm curious how this setTimeout works. Are you constantly polling for URL changes?

[mycolaos]

I meant that it's insufficient to override just one function. It involves handling not only pushState but also replaceState, popstate events, hash changes, page reloads, bookmarks, and possibly the unload event. This essentially means creating and maintaining a custom router solution that must be synchronized with Next Router. All of this results in unnecessary overhead when using a framework designed to manage routing.

The question arises: why can't I have these functionalities out-of-the-box with the Next.js router simply by having access to events?

Regarding the use of setTimeout, I previously mentioned that it is utilized instead of useEffect, indicating that the hooks provided by Next.js are leveraged to track changes.

[pbs-jmo]

I've been following this issue for a year, and it's clear that the Next.js people are not concerned about the lack of this functionality in the app router model. So I guess we won't be switching to it. For my own sanity I'll be unfollowing this thread.

[eiskalteschatten]

I agree. That's actually why we're in the process of migrating to Nuxt.js. We're concerned about the long-term and believe the writing is on the wall for the page router, despite reassurances here that it won't be deprecated any time soon. The app router is entirely inadequate for our use case and we can't wait to start the new project until it is full-featured.

[axe312ger]

Just ended up here. Holy moly. This destroy any serious projects tracking oO

[vvrnck]

What worked for me was use the provided solution of navigation-block with the addition of a custom hook that makes use of the new shallow routing feature:

export function useBackButtonNavigation(handler: (event: Event) => void) {
    const isBlocked = useIsBlocked();
    const enabled = typeof handler === 'function';

    // Persist handler in ref
    const handlerRef = useRef(handler);
    useEffect(() => {
        handlerRef.current = handler;
    });

    useEffect(() => {
        if (process.env.NODE_ENV === 'development') console.log({ isBlocked });
        if (enabled && isBlocked) {
            window.history.pushState(null, '', ''); // 👈 caveat to allow backbutton event - not the best solution, but does the trick for now

            const listener = (event: PopStateEvent) => {
                handlerRef.current(event);
                window.history.pushState(null, '', window.location.href); // preventing forward button
                return false;
            };

            window.addEventListener('popstate', listener);
            return () => {
                window.removeEventListener('popstate', listener);
            };
        }
    }, [enabled, isBlocked]);

    return null;
}

usage:

// calling the hook
useBackButtonNavigation((ev: Event) => {
        setShowLeaveDialog(true);
});

// rendering the alert/modal/dialog
<Dialog open={showLeaveDialog} onOpenChange={() => setShowLeaveDialog(false)}>
    <DialogContent className="sm:max-w-[525px]">
            <DialogHeader>
                <DialogTitle>Leave Page</DialogTitle>
            </DialogHeader>
            
            <section>
                Are you sure you want to leave the page?
            </section>

        <DialogFooter>
            <Button type="button" onClick={() => setShowLeaveDialog(false)}>close</Button>
            <Button type="button" onClick={() => confirmLeavePage()}>confirm</Button>
        </DialogFooter>
    </DialogContent>
</Dialog>

// fn to leave
const confirmLeavePage = () => {
        // logic here, clear your state, redirect, etc 
        // e.g: redirect to homepage
        router.push('/home');
}

based on this old stackoverflow answer and react-beforeunload lib.

nextjs version: 14.2.2