`useParams` triggers phantom renders on navigation

[amadeus]

I'm using React Router as a...

framework

Reproduction

I've created a repo that shows the bug with a very detailed instructions on what's happening and how to reproduce this issue:

https://github.com/amadeus/rr-params-issue

One should be able to easily clone the repo, install deps, run the dev server and then follow along with the console logs and README to get exact details on the issue.

System Info

System:
    OS: macOS 15.4.1
    CPU: (16) arm64 Apple M4 Max
    Memory: 60.70 GB / 128.00 GB
    Shell: 4.0.0 - /usr/local/bin/fish
  Binaries:
    Node: 22.14.0 - ~/.proto/shims/node
    npm: 10.9.2 - ~/.local/state/fnm_multishells/89190_1745882005446/bin/npm
    pnpm: 10.4.0 - ~/.proto/shims/pnpm
    bun: 1.2.2 - ~/.proto/shims/bun
  Browsers:
    Chrome: 135.0.7049.115
    Safari: 18.4
  npmPackages:
    @react-router/dev: ^7.5.3 => 7.5.3
    @react-router/node: ^7.5.3 => 7.5.3
    @react-router/serve: ^7.5.3 => 7.5.3
    react-router: ^7.5.3 => 7.5.3
    vite: ^5.4.18 => 5.4.18

Used Package Manager

npm

Expected Behavior

I believe the expectation is that when using a hook like useParams, it should only broadcast context updates when params actually change. I recognize that things like react compiler ultimately help downplay the effects of these updates, but I'd still argue given the surface API of hook, it should only trigger a re-render when params actually change. It's potentially a silent footgun that can be hard to reason about and plan for.

Actual Behavior

The useParams hook appears to trigger extra renders around navigation events with new params that aren't actually new and just the same params from prior to the navigation (I.E. the returned objects from useParams aren't even stable despite being shallowly equal). Then they emit after the url actually changes with the new expected params.

This results in ghost/phantom renders right before navigation events that is often already an expensive sequence of events given page navigation events.

Ultimately I think there are two core issues here:

1. useParams should only fire when params actually change
2. useParams should always return a stable object for params when they are actually shallowly equal (not really an issue if they only fire appropriately, at least from what I could tell in practice)

[timdorr]

This has been brought up before. We cannot optimize this at the library level because this may be a dependant behavior for some apps. Instead of depending on the params object itself, you should be depending on the values of the params properties. That is, you should depend on params.one or params.two in your example project.

Regardless, this will be addressed by #13073

[amadeus]

I see, ultimately it won’t really solve my specific issue because the new hooks will still fire in similar ways, it’ll just be more obvious why it is firing because of all the extra state that’s included (unless I’m reading it wrong).

I can work around this of course by building my own context providers, but I dunno, seems like it would still be nice to have a params hook that just gives me params data as it changes, since all that other router state isn’t important. But perhaps I’m of the minority opinion.

Either way, appreciate the response. 🙏

[timdorr]

You probably want to switch to using the route component props instead: https://reactrouter.com/start/framework/route-module#props-passed-to-the-component

[SlexAxton]

Following this as well. In my case I have components that aren't pages themselves that want to react to param changes without needing to thread it all through. I do agree that it'd be nice to have a useParams alternative that only caused re-renders when the params changed. I was surprised about extra render steps due to unrelated router state.

[amadeus]

You probably want to switch to using the route component props instead: https://reactrouter.com/start/framework/route-module#props-passed-to-the-component

Unfortunately these page components are also subject to these ghost renders as well, and also provide unstable param objects which forces devs to create wrapper components that listen to the param properties directly. (It's partially why I made those memo wrappers in the demo repo to begin with, since otherwise it was tricky to track down what and where was triggering re-renders)

Ultimately the workaround that I have for anyone else coming into this thread, is to create a new special context for params that you listen too instead, this is what it looks like (make sure to basically put it up at the top of your application so any sub page will inherit from it):

import { type ReactNode, createContext, useContext, useInsertionEffect, useRef } from 'react';
import { type Params, useParams as useParamsRR } from 'react-router';

const SafeParamsContext = createContext<Readonly<Params<string>>>({});

interface SafeParamsContextProviderProps {
  children: ReactNode;
}

export function SafeParamsContextProvider({ children }: SafeParamsContextProviderProps) {
  const params = useParamsRR();
  const lastParams = useRef(params);
  const didChange = JSON.stringify(lastParams.current) !== JSON.stringify(params);
  useInsertionEffect(() => {
    if (didChange) {
      lastParams.current = params;
    }
  }, [didChange, params]);
  return (
    <SafeParamsContext.Provider value={didChange ? params : lastParams.current}>
      {children}
    </SafeParamsContext.Provider>
  );
}

export function useParams<
  ParamsOrKey extends string | Record<string, string | undefined> = string,
>(): Readonly<[ParamsOrKey] extends [string] ? Params<ParamsOrKey> : Partial<ParamsOrKey>> {
  return useContext(SafeParamsContext) as Readonly<
    [ParamsOrKey] extends [string] ? Params<ParamsOrKey> : Partial<ParamsOrKey>
  >;
}

Ultimately I think my thoughts on the matter would be that library APIs should do their best to avoid accidental developer foot guns, and in my experience it's quite easy for sufficiently complex react apps to suffer from death by a thousand cuts -- nothing performing egregiously bad, just sluggish.

I also understand you're balancing a lot of different requirements in building a generalized library/framework, so just here to express my concerns and I hope I don't come across as annoying. 🙏