Declarative mask on search parameters applies previous route’s search state instead of the new one

[LouisBouch]

Which project does this relate to?

Router

Describe the bug

When using a declarative mask on search parameters, the prev argument in the mask’s search function contains search values from the previously active route instead of the search parameters defined on the clicked Link.

More precisely, the search function runs 4 times upon clicking on the masked route's Link.

• For the first two, prev contains search values from the previously active route.
• For the next 2, it contains the search parameters defined on the currently clicked Link.

However, the resulting URL reflects the values from the first two calls (the stale route’s parameters), rather than the intended values from the clicked Link.

Mask

const homeMask = createRouteMask({
  routeTree,
  from: "/other",
  to: "/other",
  search: (prev) => {
   // The timestamp is used to emphasize the console output, it is otherwise not needed. 
    const timestamp = new Date();
    
    let val = prev.query + " " + timestamp.getMinutes() + "minutes" + " " + timestamp.getSeconds() +"seconds";
    console.log(val);

    return {
      ...prev,
      query: val,
      hasDiscount: undefined,
    };
  },
});

Links

<Link
  to="/profile"
  search={{
     query: "profile",
     hasDiscount: true,
  }}
>
  Prof
</Link>
<Link
  to="/other"
  search={{
    query: "other",
    hasDiscount: true,
  }}
>
  other
</link>

Type validation (same for both routes)

export const Route = createFileRoute("/profile")({
  component: RouteComponent,
  validateSearch: ({ query, hasDiscount }): ret => {
    return {
      query: query as string | undefined,
      hasDiscount: hasDiscount as boolean | undefined,
    };
  },
});

Your Example Website or App

https://stackblitz.com/edit/vitejs-vite-4dj9qsmg?file=src%2FApp.tsx

Steps to Reproduce the Bug or Issue

1. After opening the link, open the preview in a new tab using the top right button (Cannot see the url otherwise).
2. Click on the Profile Link
3. Open the console and clear it
4. Click on the Other Link.
5. Observe:
   • The url contains .../other?query=profile...
   • The console logs 4 outputs, two from the mask running on the profile route and 2 outputs from the mask running on the other route. All 4 outputs ran at the same time.

Expected behavior

The url should instead contain: .../other?query=other...

Instead of using the previous route's search parameters, the mask should use the parameters from the activated Link.

Screenshots or Videos

Console logs after clicking on "profile" and after clicking on "other".

Url after clicking on "profile". (Normal, no masking)

Url after clicking on "other". (Masking, but with value of profile)

Platform

• Router Version: 1.131.31
• Browser: Chrome, Firefox
• React Version: 19.1.1
• Bundler: vite
• Bundler Version: 7.1.3

Additional context

The documentation for masking only includes a full example for masking using path parameters. The documentation also does not mention this specific use case. That being said, I was able to reproduce the desired behavior using imperative masking, which makes me believe this behavior is not desired.

[nlynzaad]

Thanks for raising this.

You are right this is not supposed to be running 4 times. In your example this should actually only run twice when clicking on the "/other" path and once for all other paths. I've addressed this problem in #5081

When using masking it doesn't actually change the search parameters but just "masks" them from being visible in the url. That means that when the masking is being run it needs to "intercept" the navigation, mask the url, and then complete the navigation using the actual parameters. Therefore, prev in the search function will actually refer to the previous search parameters and not the current as these are the previous parameters prior to navigation.

It is important to note that since the mask is dependent on the search parameters in a dynamic manner, i.e. dependent on prev and time, it does need to recalculate the href for the link with each navigation. hence you will see the function running, in your case, on every link you click and twice when clicking on "/other", i.e. once for navigation and once for updating the href after navigation.

[LouisBouch]

Amazing, I pulled the changes and can now see the doubling has disappeared.

As for the other "issue" I brought up, which might simply be me misunderstanding the functionality of the declarative mask, is what you're saying that prev will always contain the previous search's contents? Therefore, if I wish to hide only a certain parameter (hasDiscount in this cast) from the search, I cannot use:

return {
      ...prev,
      hasDiscount: undefined,
    };

As this will fill the other search parameters with ...prev, which are the previous search's contents. More concisely, is imperative masking the only way to fulfill my masking need, which requires the masking of only 1 search parameter?

[nlynzaad]

In your use case, imperative is probably the best way to go.