How to scope retainSearchParams to only child routes

[CBell045]

Hi there,

I want to retain search parameters across navigations but only while navigating between a route and its descendants; I do not want the params to be retained between sibling routes, even if those routes have the same param name.

Example:

// /posts/route.tsx and /users/route.tsx both have:
validateSearch: z.object({ search: z.string().optional() }),
search: { middlewares: [retainSearchParams(true)] },

// On /posts?search=foo:
<Link to="/posts/$id" params={{ id }} /> // /posts/1?search=foo  (good)
<Link to="/users" />                     // /users?search=foo    (bad)

Any ideas on how to do this? Thanks!!

[Harshul1484]

This happens because of how search middlewares run. When a link is built, the router collects the search.middlewares of the destination route and its parents, and runs them with search set to the current URL's search params (buildLocation / getSearchMiddlewares in router-core's router.ts). The middleware context is only { search, next, meta }, with nothing about which route you're coming from.

So on /posts?search=foo, <Link to="/users" /> runs /users's own retainSearchParams(true), which sees search: 'foo' in the current URL and keeps it. /posts's middleware isn't involved at all.

Option 1: give each section its own key (no custom code)

// posts/route.tsx
validateSearch: z.object({ postsSearch: z.string().optional() }),
search: { middlewares: [retainSearchParams(['postsSearch'])] },

// users/route.tsx
validateSearch: z.object({ usersSearch: z.string().optional() }),
search: { middlewares: [retainSearchParams(['usersSearch'])] },

A key list only copies those keys. /posts?postsSearch=foo → /users has nothing to retain, while /posts/$id still inherits postsSearch because /posts is its parent. Use a list rather than true here: true copies every current key, which is what causes the leak.

Option 2: keep the same key, only retain when you're already inside the section

Wrap the built-in middleware so it only runs when the current path is under the route's own path, and otherwise behaves as if there were no middleware:

import { retainSearchParams, type SearchMiddleware } from '@tanstack/react-router'

function retainWithin<T extends object>(basePath: string): SearchMiddleware<T> {
  const retain = retainSearchParams<T>(true)
  return (ctx) => {
    const path = window.location.pathname
    const inside = path === basePath || path.startsWith(`${basePath}/`)
    return inside ? retain(ctx) : ctx.next(ctx.search)
  }
}

// users/route.tsx
search: { middlewares: [retainWithin('/users')] },

ctx.next(ctx.search) is what runs when there's no retain middleware: the link's own search (or none, which gives {}) decides the result. window.location.pathname works for a browser-history SPA. If you use a basepath, hash history or SSR, read the current path from your router instance instead (router.state.location.pathname).

[CBell045]

Option 2 is helpful but I don't think you can access router.state.location.pathname in the middleware and I'd rather not rely on window.location.pathname

[Rami-init]

The middleware context is only { search, next, meta }, but you can hand it the router through a small module (importing router.tsx into a route file would be circular):

// router-ref.ts
import type { AnyRouter } from '@tanstack/react-router'

let router: AnyRouter | undefined
export const setRouter = (r: AnyRouter) => { router = r }
export const isInside = (routeId: string) =>
  router?.state.matches.some((m) => m.routeId === routeId) ?? false

// retain-within.ts
import { retainSearchParams, type SearchMiddleware } from '@tanstack/react-router'
import { isInside } from './router-ref'

export function retainWithin<T extends object>(routeId: string): SearchMiddleware<T> {
  const retain = retainSearchParams<T>(true)
  return (ctx) => (isInside(routeId) ? retain(ctx) : ctx.next(ctx.search))
}

// main.tsx
const router = createRouter({ routeTree })
setRouter(router)

// routes/posts/route.tsx
search: { middlewares: [retainWithin('/posts')] },

// routes/users/route.tsx
search: { middlewares: [retainWithin('/users')] },

Result on @tanstack/react-router 1.170.39:

from                 to           href
/posts?search=foo    /posts/$id   /posts/1?search=foo
/posts?search=foo    /users       /users
/posts/1?search=foo  /users/$id   /users/2
/users?search=bar    /users/$id   /users/2?search=bar
/users?search=bar    /posts/$id   /posts/1

This is client-side only: with SSR, the module-level ref would be shared between requests. If you want no module state at all, remove the middleware and set search={true} on the links inside the section.