Skip to content

docs: add info about zod 4 #4823

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: add info about zod 4 #4823

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
16206b0
docs: add note about zod 4 native support
niba Jul 29, 2025
ecc723c
docs: add info about zod mini
niba Aug 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 44 additions & 2 deletions docs/router/framework/react/guide/search-params.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,9 +201,51 @@ It might be surprising that when you try to navigate to this route, `search` is

For validation libraries we recommend using adapters which infer the correct `input` and `output` types.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be more relaxed, as Zod v4 is now the opposite? Like "For some validation libraries..."?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be honest, I don’t understand the Adapters section. What are we trying to say here? I also tested the example in that section and it isn’t true. ⁠Link doesn’t require ⁠search to be defined, because all fields are optional (tested with Zod v3). Moreover, we already covered transforming search params with ⁠.default() in the previous section so I don't know why we write it like introduction to this topic.

So I think we should rewrite it or remove it, especially right now that we use the adapter only in Zod 3.


### Zod
### Zod 4

An adapter is provided for [Zod](https://zod.dev/) which will pipe through the correct `input` type and `output` type
> [!WARNING]
> Zod v4.0.6 or higher is recommended for proper type inference.

When using [Zod 4](https://zod.dev/) an adapter is not needed to ensure the correct `input` and `output` types are used for navigation and reading search params. This is possible thanks to `zod` enhanced type inference, which preserves complete type information when using [Standard Schema](https://github.com/standard-schema/standard-schema).

```tsx
import { createFileRoute } from '@tanstack/react-router'
import { z } from 'zod'

const productSearchSchema = z.object({
page: z.number().default(1),
filter: z.string().default(''),
sort: z.enum(['newest', 'oldest', 'price']).default('newest').catch('newest'),
Comment on lines +217 to +218
Copy link
Contributor

@KiwiKilian KiwiKilian Aug 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be great to have a few words on the difference of .default() and .default().catch().

Also, when the default is used already twice, should we recommend the pattern from the search middlewares of using an defaultValues object?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the docs earlier on this page explain when to use ⁠default and when to use ⁠catch.

I follow the same style as used in the rest of the adapters. I think that the choice about using defaultValues belongs to the developer and is not important here, especially since the values that you put into default and catch are checked by TypeScript

Copy link

@LargatSeif LargatSeif Aug 4, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in case you want to include any zod/v4-mini examples :
catch:

validateSearch:z.object({
    redirectTo: z.catch(z.string(), "")
})

default:

validateSearch:z.object({
    redirectTo: z.catch(z._default(z.string(), ""), ""),
})

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the docs earlier on this page explain when to use ⁠default and when to use ⁠catch.

But it doesn't explain why one would use default and catch on the some line which was quite confusing to me in the beginning.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While using the defaultValues is absolutely optional here, it's a required pattern for the search middleware default stripping to allow instance comparison. So I would think this would make the docs more aligned in recommending that patter subtly, but it's true other parts of the docs also don't use it.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the docs earlier on this page explain when to use ⁠default and when to use ⁠catch.

But it doesn't explain why one would use default and catch on the some line which was quite confusing to me in the beginning.

You’re right. I’ll add explanation. In general, it’s tricky because ⁠.catch() normally behaves like ⁠.default(), but its behaviour changes when you combine it with ⁠.optional(). It also produces a different type, since ⁠.default() makes the field optional.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While using the defaultValues is absolutely optional here, it's a required pattern for the search middleware default stripping to allow instance comparison. So I would think this would make the docs more aligned in recommending that patter subtly, but it's true other parts of the docs also don't use it.

I can change all the examples to use defaultValues everywhere, I don't have a strong opinion about it

})

export const Route = createFileRoute('/shop/products/')({
validateSearch: productSearchSchema,
})
```

Alternatively, you can use the [Zod Mini](https://zod.dev/packages/mini) variant

```tsx
import { createFileRoute } from '@tanstack/react-router'
import * as z from 'zod/mini'

const productSearchSchema = z.object({
page: z._default(z.number(), 1),
filter: z._default(z.string(), ''),
sort: z.catch(
z._default(z.enum(['newest', 'oldest', 'price']), 'newest'),
'newest',
),
})

export const Route = createFileRoute('/shop/products/')({
validateSearch: productSearchSchema,
})
```

### Zod 3

An adapter is provided for [Zod 3](https://v3.zod.dev/) which will pipe through the correct `input` type and `output` type

```tsx
import { createFileRoute } from '@tanstack/react-router'
Expand Down