Numeric strings in search params issue

[vixducis]

Describe the bug

Consider the following scenario:

• You have a route where you accept a string as a search param. (validate it with zod)
• Pass a numeric string as a search param through the route. (e.g. navigate({search: {test: '3'}))
• You'll see that an error is thrown, this is because the router will receive the query param as a number, and the zod validator will consider it illegal as it is not a string

Your Example Website or App

https://stackblitz.com/edit/github-fbut9a-bu53ju?file=src/IndexComponent.tsx

Steps to Reproduce the Bug or Issue

• Open the stackblitz
• Click on the Set test param to 3 // should fail button.
• An error will be thrown

Expected behavior

I would hope the search param could be considered a string. I don't know if the casting could be done based on the validation?

Screenshots or Videos

No response

Platform

• OS: Windows
• Browser: Firefox
• • Version: 110

Additional context

No response

[Bailig]

After digging into the code, I found that the search params are parsed here:

router/packages/router/src/searchParams.ts

Lines 4 to 29 in 2abd72e

	export const defaultParseSearch = parseSearchWith(JSON.parse)
	export const defaultStringifySearch = stringifySearchWith(JSON.stringify)
	export function parseSearchWith(parser: (str: string) => any) {
	return (searchStr: string): AnySearchSchema => {
	if (searchStr.substring(0, 1) === '?') {
	searchStr = searchStr.substring(1)
	}
	let query: Record<string, unknown> = decode(searchStr)
	// Try to parse any query params that might be json
	for (let key in query) {
	const value = query[key]
	if (typeof value === 'string') {
	try {
	query[key] = parser(value)
	} catch (err) {
	//
	}
	}
	}
	return query
	}
	}

router/packages/router/src/qss.ts

Lines 28 to 54 in 2abd72e

	function toValue(mix) {
	if (!mix) return ''
	var str = decodeURIComponent(mix)
	if (str === 'false') return false
	if (str === 'true') return true
	if (str.charAt(0) === '0') return str
	return +str * 0 === 0 ? +str : str
	}
	export function decode(str) {
	var tmp,
	k,
	out = {},
	arr = str.split('&')
	while ((tmp = arr.shift())) {
	tmp = tmp.split('=')
	k = tmp.shift()
	if (out[k] !== void 0) {
	out[k] = [].concat(out[k], toValue(tmp.shift()))
	} else {
	out[k] = toValue(tmp.shift())
	}
	}
	return out
	}

Search params are from URL so they are always string, and it's parsed based on the value be default. You can pass a custom parser to the router.

const router = new ReactRouter({
  routeTree,
  parseSearch: (searchStr) =>
    searchStr
      .slice(1)
      .split('&')
      .reduce((acc, pair) => {
        const [key, value] = pair.split('=')
        acc[key] = value
        return acc
      }, {} as Record<string, string>),
})

[vixducis]

Ok, but since the parseSearch is defined on the router, I would have to decide between having the numeric strings or numbers for all of my routes. I would really like to decide on the route level whether a given search param is a string or a number.

[vixducis]

I found a better solution myself: the preprocess zod function. This should work:

validateSearch: z.object({
    test: z.preprocess(
        (test) => (test === undefined ? undefined : `${test}`),
        z.string().optional()
    )
})

[maxwellwalin]

I was running into this issue as well, especially when it came to having a user input search string that could start with a number, or an ID string that starts with a number. I've done the same thing, but I minimized and abstracted it to be used in my search validation schemas:

export const OptionalStringURLParam = z.preprocess(String, z.string().optional())

The router's parsing of the params have something to do with this. Probably a PR that could solve this issue, since it is even parsing strings that only start with a number, and contain many other string-only characters.

[Avivhdr]

In some cases, this is not enough.
When passing 0.0 as a param, useSearch shows it as a 0.
Coercing/preprocessing this to a string results in "0", while the desired result is "0.0"

[cdeutsch]

This still seems to be an issue.

Numbers are valid strings.

Why is it doing the conversion to a number BEFORE checking for the type that it expects?

[isnifer]

@schiller-manuel any chance to fix parsing and make id="123" to just id=123 even if validateSearch: z.object({ id: z.string() })?
You really don't need any pre/post processing if I'm asking about a string.

[schiller-manuel]

@isnifer I fail to understand the request here. if your schema expects a string, it won't accept a number. neither in types nor at runtime

[isnifer]

@schiller-manuel I'm sorry, I will try again.

I've created a demo here https://tsr-issue-537.netlify.app/

And the code is here — https://github.com/isnifer/tanstack-issue-537/blob/master/src/routes/issue.tsx

The problem is that Router interprets Strings that look like a Number as Numbers at some point.
This behavior introduces 2 major issues:

1. Numeric strings wrapped with double quotes — they shouldn't.
2. If the numbers (that I expect to read as strings in my schema) are too large — they are modified.

So when I will pass &numericString=723421968459640832 to url it will be transformed twice:

1. 723421968459640832 became 723421968459640800 (since it's too big for Number)
2. And it will be wrapped with "" and became &numericString="723421968459640800"

I recorded an example and made it slow to 0.25x, you can see how the Router transforms the URL.
You can find out on the 00:08 how it make these 2 changes.

screen-recording-2025-12-06-at-043738_gL4Be7DF.mov

And yes I see your response here #989 (comment)

to transform big numbers to add double quotes, but cmon, it should not be double quotes for numeric strings at all.

UPD: I've added second page with the same Zod schema where I need to parse z.coerce.string() value from params – and it just works. No double quotes, no transformation from URL => number => string. And added example with EXPECTED issue of casting from string to number (z.coerce.number()) to show the difference.

[isnifer]

@schiller-manuel do I need to create a new issue?