Allow passing `search` string in `useRouter` methods

[hugotiger]

Is your feature request related to a problem? Please describe.

In our app we sometimes need to pass along a search string, e.g. from window.location.search. This works great with the Link component since you can pass it to the href like this:

<Link href={{ pathname: '/about', search: window.location.search }}>
  About
</Link>

But if you need to do programmatic routing using push/replace this requires you to pass it as a query object instead (especially if you're using type-safe routing):

push({ pathname: 'about', query: { ... }})

I can't find any simple way of passing an already encoded search string to push or replace. Also it's a little bit unclear to me how the query would be encoded. For example how could one customize how array values are encoded?

Describe the solution you'd like

It'd be great if a search string could be passed to push and replace. This would also enable doing advanced patterns such as:

const searchParams = new UrlSearchParams({ returnTo: window.location.search })

push({ pathname: 'about', search: searchParams.toString() })

Describe alternatives you've considered

Allow passing URLSearchParams to the push and replace methods. Could make sense since that's a fairly well adopted standard. The URLSearchParams standard has some problems though and it doesn't solve supporting different encodings of e.g. array values.

It would be nice if the typed pathnames always allowed suffixing with a search string or hash, like Next.js typedRoutes support. This wouldn't work great with dynamic routes though (push('/[slug]?foo=bar') doesn't really make sense)

[amannn]

Hmm, I see your point. I'm not sure if accessing a string is the best option here though.

The canonical way to access search params in Next.js is either the searchParams prop in Server Components or useSearchParams in Client Components. The former already works well with the APIs from next-intl, since the existing object can be spread into query. However the latter is not so well supported.

Internally, we're converting query to URLSearchParams in order to serialize values via toString():

next-intl/packages/next-intl/src/navigation/shared/utils.tsx

Lines 69 to 87 in c9e7a18

	export function serializeSearchParams(
	searchParams: Record<string, SearchParamValue>
	) {
	function serializeValue(value: SearchParamValue) {
	return String(value);
	}
	const urlSearchParams = new URLSearchParams();
	for (const [key, value] of Object.entries(searchParams)) {
	if (Array.isArray(value)) {
	value.forEach((cur) => {
	urlSearchParams.append(key, serializeValue(cur));
	});
	} else {
	urlSearchParams.set(key, serializeValue(value));
	}
	}
	return '?' + urlSearchParams.toString();
	}

I could imagine overloading query to also allow an instance of URLSearchParams. If you want to use window.location.search, you could use that to instantiate it: new URLSearchParams(window.location.search).

The URLSearchParams standard has some problems though

That's interesting, thanks for sharing! It seems like, based on the feedback from the maintainers of Chromium and WebKit, these are here to stay though and URLSearchParams might remain the commonly used interface for interacting with search params.

[hugotiger]

Thanks for the quick reply!

Hmmm I'm torn here. On one hand handling loose strings isn't great... But at the same time I think it makes sense to support the URL class like in the Link component, not only in this library, but also in Next.js natively.

Reading from the MDN docs it sounds to me like URLSearchParams are more for parsing and modifying existing search params, whilst location.search often is used for accessing and setting search params in the URL.

Allowing search strings also allows full control over the encoding. For example to have comma-delimited arrays, often done through the popular query-string NPM package, and now increasingly through NUQS. This is actually one of the key problems I'm trying to handle where we need to support comma-delimited array values until all of our tooling handles URLSearchParams properly.

Whilst adding an overload for URLSearchParams would probably be an improvement, to me we can wait and see if any other person experiences similar issues, or if maybe there's some other solution not thought of here.

I'd love to hear your thoughts! But rant aside...

Do you see any way comma delimited arrays could be handled without TS yelling? Basically I want to be able to do something along the lines of: push("/some-pathname?arbitrary-search-string-with-comma-delimited-array-value").

[amannn]

Hmm, good point—I saw though that nuqs seem to move to URLSearchParams-style array support: 47ng/nuqs#484. Might be worth keeping an eye on that.

For working with Link, nuqs suggests a serializer helper. Maybe a string could indeed be interesting to support for better compatibility with this.

Do you see any way comma delimited arrays could be handled without TS yelling?

I think this should work:

router.push({
  pathname: '/users',
  query: {array: 'item1,item2,item3'}
})

It's unfortunately only one property at a time. Could that work for you?

we can wait and see if any other person experiences similar issues, or if maybe there's some other solution not thought of here.

Yeah, maybe a good idea. Would be interesting to see where nuqs moves here. I'm also curious if Next.js will make a change here at some point to unify APIs across Link and useRouter—currently the API differences seem a bit odd to me.

[hugotiger]

Hi again! Been quite busy, but I've now finally opened a discussion in the Next.js repo regarding this! Feel free to chime in if you have any thoughts/feedback 😄