[RFC]: Type-Safe URL Search Params for useSearchParams hook
#13713
Replies: 5 comments 19 replies
-
|
A few questions:
|
Beta Was this translation helpful? Give feedback.
-
I've updated the RFC to address these concerns. And here's a summarized reply: Here are the replies to your questions:
|
Beta Was this translation helpful? Give feedback.
-
Thanks for mentioning these @rossipedia. These your concerns highlighted major problems with the proposal, which I've updated. Here's the summary:
|
Beta Was this translation helpful? Give feedback.
-
|
I'll note that search params are also often used in Also What I don't understand is why I both need to export the schema from the route AND pass the schema into const [params, setParams] = useSearchParams({ schema: searchParamsSchema });I don't see any places where the React Router generated types or compiler is being used. In fact, I believe it would be trivial to create a user land implementation that has the same API signature as what you have right now without requiring any changes to React Router. I suggest you include such a user land implementation in your proposal, specifically so you can point out how what you are proposing is impossible to do entirely in user land. It's not obvious to me right now. Also This answer
Seems to conflict with this answer
If it becomes the default or null without erroring, then what's the point of the validation library? If we are going to require a validation library and integrate it into the framework, I would at least expect it to optionally throw errors if the validation doesn't work out so my error boundary can catch it. Also
If the routes are in conflict, then that will cause errors. I would assume, at very least, that if this were to become an integrated feature of React Router that the compiler would at least warn of these potential conflicts. |
Beta Was this translation helpful? Give feedback.
-
|
I think I'm still landing on this:
While I can see this being cool and a nice to have if it fits your use-case and general principles, I don't particularly like the idea of every const { searchParams } = new URL(request.url);
const typedParams = z.object({ ... })
.parse(Object.fromEntries(searchParams))
.catch({
// default values
}); |
Beta Was this translation helpful? Give feedback.
-
|
Without explicitly declaring search param schemas in the route itself, you’re stuck guessing. You might validate in one place, but there’s nothing stopping another component from navigating with invalid, partial, or conflicting state. Constraint is what makes coordination possible. It’s what allows non-local callers to participate safely. The impression I want to give here is that, even with nuqs or a basic zod schema, your team and your code needs some level of discipline to always use them, cause no constraint stops them from doing otherwise. |
Beta Was this translation helpful? Give feedback.
-
|
Without getting too deep in the weeds here, this proposal should be targeting the routes.ts file rather than another export bloating the surface API as @alexanderson1993 mentioned. This needs very careful consideration of locking in a validation library (or requiring one at all?) and should be typegen first.
|
Beta Was this translation helpful? Give feedback.
-
|
I really appreciate you guys being interested in this. I want to clarify first that this is still just an RFC and not yet a well thought out API design. These concerns you and @alexanderson1993 have highlighted are crucial areas to consider, which the RFC yet doesn't have a clear answer to. Although being a competing framework, I'm highly motivated that TanStack Router's approach to type-safe search params answers most of these questions, and probably we can adopt similar patterns. Still yet, the questions on programmatically adding params and the Form's Get method are still unanswered. My plea is, with interventions from you guys and from other community members, we can keep refining this RFC till it's mature enough to advance the proposal to stage 1. For now, I'm reasoning on how to update the RFC to address these newly highlighted concerns. |
Beta Was this translation helpful? Give feedback.
-
|
I have some thoughts about implementing type-safety searchParams into react-router though I chose a slightly different approach.
export function validateSearchParams<T>(search: URLSearchParams): T;It won't require any library ( type User = { name: string; email: string }
export function validateSearchParams(search: URLSearchParams) {
const name = search.get('user') || ''
const email = search.get('email') || ''
return { name, email }
}Same for import * as v from 'valibot'
const userSchema = v.object({ user: v.string(), email: v.string() })
export function validateSearchParams(search: URLSearchParams) {
return v.parse(userSchema, Object.fromEntries(search))
}
The flow of execution should look like that: Server: Thanks to that we can set new property in export function validateSearchParams(url: URLSearchParams) {
return { user: ..., email: ... }
}
export async function loader({ search }: Route.LoaderArgs) {
// do something with search
}
export default function Route({ search }: Route.ComponentProps) {
const { user, email } = search
return <p>{user}</p>
}
In that case import * as IndexRoute from './index.tsx'
// or import { validateSearchParams as indexSearchParams } from './index.tsx'
export function validateSearchParams(search: URLSearchParams) {
return {
...Route.validateSearchParams(search),
filter: { sort: 'desc' }
}
}
import { Link } from 'react-router'
<Link to={{ pathname: href('/users/:id', { id: '1' }), search: search('/users/:id', { filter: {} }) />Unfortunately in that case we duplicate param export function href<Path extends keyof Args>(
path: Path,
...args: Args[Path]
): stringIf we could safely change it into this: export function href<Path extension keyof Args>(path: Path, args: Args[Path], search: SearchArgs[Path])Then we would have fully typed import { Link } from 'react-router'
<Link to={href('/users/:id', { id: '1' }, { filter: {} })} />
// or
<Link to={href('/users/:id', { id: '1' }, prev => ({ ...prev, filter: {} }) } />
|
Beta Was this translation helpful? Give feedback.
-
|
First part looks like something a middleware would solve. const SearchParamsContext = unstable_createContext<{ name: string; email: string }>()
export const unstable_middleware: Route.unstable_MiddlewareFunction[] = [
async ({ request, context }, next) => {
let url = new URL(request.url);
let name = url.searchParams.get("name") ?? ""; // manual
let email = z.string().email().parse(url.searchParams.get("email") ?? ""); // zod
context.set(SearchParamsContext, { name, email });
return await next();
}
]
export async function loader({ context }) {
let { name, email } = context.get(SearchParamsContext);
// use them
return { name, email }
}
export default function Component({ loaderData }: Route.ComponentProps) {
// use loaderData.name or loaderData.email
}The only difference, which may be nice, is that you won't need to return them from the loader in the For this: export function validateSearchParams(search: URLSearchParams) {
return {
...Route.validateSearchParams(search),
filter: { sort: 'desc' }
}
}I would make it so this function receives the parent route validated search params instead: export const validateSearchParams: Route.ValidateSearchParamsFunction = (searchParams, parentParams) => {
return {
// this is correctly typed automatically, similar to ComponentProps["matches"]
...parentParams,
filter: { sort: 'desc' } // more params validated here
};
}This <Link to={{ pathname: href('/users/:id', { id: '1' }), search: search('/users/:id', { filter: {} }) />Looks too complex, I would try to make it so we could pass search params to Also I like this idea: href('/users/:id', { id: '1' }, prev => ({ ...prev, filter: {} })The Fully agree on point 5 and 6. |
Beta Was this translation helpful? Give feedback.
-
I agree with your points 1-4 and 6, and I also like @sergiodxa's suggestion for passing the parent's validator. We also need to address serialization and deserialization for deeply nested objects, moving away from dependencies like However, I don't support point 5. The RFC's title, "Type-Safe URL Search Params for
When This does reintroduce the problem of resolving conflicts when same-key parameters have different schemas. This issue already exists with the untyped version. Our solution is to give developers explicit control over conflict resolution. Conflict Resolution MechanismHere's how we achieve that: // Define a map of all route validator function types
type SearchValidators = {
[Path in keyof Params]: (
search: URLSearchParams,
parentValidator: SearchValidators[keyof Params] | undefined,
) => any
}
// Internal function to get the search params validator of a path
function getSearchValidatorFromPath<Path extends keyof Params>(
path: Path,
): SearchValidators[Path]
// The enhanced useSearchParams hook
function useSearchParams<T, Path extends keyof Params>(
validateSearchParams: (
search: URLSearchParams,
// The specific validator function for the 'from' path is passed here
routeValidator: SearchValidators[Path],
) => T,
from: Path, // Explicitly specify the path for context
): [T, (update: Partial<T> | (prev: T) => Partial<T>) => void] {
const routeValidator = getSearchValidatorFromPath(from)
const searchParams = validateSearchParams(
URLSearchParams,
routeValidator,
)
// Remaining implementation
return [searchParams, () => {}] // Placeholder return
}By explicitly specifying the We should also fully address how this serialization/deserialization will be integrated into the useSearchParams hook, especially for complex types. |
Beta Was this translation helpful? Give feedback.
-
|
I have a short disclaimer for my suggestions. URLSearchParams: parsing and serializationI suggested new exported property from Route Module: type User = { name: string; email: string }
export function validateSearchParams(search: URLSearchParams) {
const name = search.get('user') || ''
const email = search.get('email') || ''
return { name, email }
}I have to disagree with it. That kind of defintion will solve issues like type User = { name: string; roles: string[] }
export function validateSearchParams(search: URLSearchParams) {
const name = search.get('user') || ''
const roles = search.get('roles') || ''
return { name, roles: roles.split(':') }
}It's still easy and doable. Worse with serialization. Devs will have to remember serialize Solution for that would be changed signature for Route's Module property: type Parser<T> = (search: URLSearchParams) => T
type Serializer<T> = (value: T) => URLSearchParams
const defaultSerializer = (value: unknown) => {
return new URLSearchParams(JSON.stringify(value))
}
function defineSearchParams<T>(parser: Parser<T>, serializer: Serializer<T> = defaultSerializer) {
return { parser, serializer }
}
export const searchParams = defineSearchParams(
(search) => ({
name: search.get("name") || "",
roles: (search.get("roles") || "").split(":")
}),
(value) => new URLSearchParams({
name: value.name,
email: value.roles.join(':')
})
)
// or with createBrowserRouter
let router = createBrowserRouter([
{
path: "/projects/:projectId",
Component: Project,
searchParams: defineSearchParams()
// or without the helper
searchParams: {
parser: (search) => ({}),
serializer: (values) => new URLSearchParams() // <- serializer is optional
}
},
]);
type Parser<T> = (search: URLSearchParams) => T
type Serializer<T> = (value: T) => URLSearchParams
type SearchParams<T> = {
parser: Parser<T>
serializer: Serializer<T>
}My problem with that approach is... I don't know how to connect TimingRecently François Best (author of nuqs) wrote a really nice article about search params: Beware The URL Type-Safety Iceberg. One of his concerns is timing and how often website can change url in the browser. I do like keep the state in Every "save" action (that change the state) should require real change action, like clicking the Same suggestion I have for |
Beta Was this translation helpful? Give feedback.
-
|
In my opinion type safe search params should be implemented in the routes definition: export default [
index("./home.tsx"),
route("/about", "./about.tsx"),
route("/city", "./city.tsx", { searchParam1: z.string() }),
] satisfies RouteConfig;This way you also have type safe href('/city', { searchParam1: 'x' })You get type safe search params in components routes: export default function Page({ params: { searchParam1 }: Route.ComponentProps }) {
// ...
} |
Beta Was this translation helpful? Give feedback.
-
Take a look at this comment. However, I'd still prefer leaving the
type User = { name: string; email: string }
export function validateSearchParams(search: URLSearchParams) {
const name = search.get('user') || ''
const email = search.get('email') || ''
return { name, email } as User
}and also allows to colocate routing logic better. Let the route modules file be the single source of truth for routing logic. I don't want to, after centralising all routing logic for a |
Beta Was this translation helpful? Give feedback.
-
|
I think there are problems with that approach.
We have to see the difference between react-router (global elements, hooks, etc like state navigation), route module (loaders, actions, component) and the glue sticking it together ( |
Beta Was this translation helpful? Give feedback.
-
You can extend the fs routes with the one that define search params: import type { RouteConfig } from '@react-router/dev/routes'
import { flatRoutes } from '@react-router/fs-routes'
export default flatRoutes().then((fsRoutes) => {
return [
...fsRoutes,
route("/city", "./city.tsx", { searchParam1: z.string() }),
] satisfies RouteConfig
})
That's to be expected. |
Beta Was this translation helpful? Give feedback.
-
|
That RFC isn't only about type-safety. SearchParams should work in framework mode as in data mode. In data mode it should be possible to do: let router = createBrowserRouter([
{
path: "/",
loader: async ({ search } /* <- result of validateSearchParams */) => {
// return data from here
return { records: await getSomeRecords() };
},
Component: Project,
validateSearchParams: (search) => ({}),
},
]);Then first thing that should happen is Maybe there's a problem with RFC's name or I don't understand something. I don't think about type-safety as |
Beta Was this translation helpful? Give feedback.
-
|
The purpose of the RFC is for type-safe search params with compile-time (TypeScript) and runtime-time validations. And yes, the feature should be available in other modes as directed by the GOVERNANCE.md - New Feature Process. The RFC is also aimed at bringing this type-safety to the I really see light in the suggestions from @grz-gajda, but @remorses, if there are other valid reasons you're pushing for the |
Beta Was this translation helpful? Give feedback.
-
|
I opened a separate RFC for adding the search params in the |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
RFC: Type-Safe URL Search Parameters for
useSearchParamsLast Edited: June 9, 2025
This proposal is made according to the guidelines provided here: GOVERNANCE.md - New Feature Process.
Edit Summary
This RFC is pending edits to address newly highlighted concerns and suggestions. Please refer to this thread for a more likely path forward for the proposal.
Problem
useSearchParamscurrently exposes the untypedURLSearchParamsAPI. This results in runtime errors, boilerplate, and poor developer experience due to a lack of compile-time safety, inconsistent with React Router's strong type support for path parameters and loader/action data.Motivation
To elevate
useSearchParamsto the same standard of type safety as other core React Router APIs. By integrating a standard schema-based approach for search params, we can:useSearchParamswith the library's existing type system.typegen), seamless type consistency forloadersandactions, and overall API standardization, cannot be effectively achieved or maintained in user-land without significant boilerplate or breaking the "Routing and Data Focused" design principle.Proposed Solution: New
searchParamsSchemaRoute Module Export & EnhanceduseSearchParamsHookWe propose introducing a new, optional
searchParamsSchemaexport within route modules. This export would be an object returned by a React Router utility (e.g.,defineSearchParams) that encapsulates individual schema definitions for each search parameter.react-router typegenwould process this to type the route'sInfoobject. Concurrently, theuseSearchParamshook will be enhanced to accept an optional schema, providing typed state when a schema is provided, while maintaining backward compatibility by returning an untypedURLSearchParamsobject when no schema is passed.New Utilities and Concepts
defineSearchParamsutility: A new function used to create search parameter schemas. It takes a plain object where each property's value is an individual schema definition (e.g.,z.string(),z.number()). These schemas can be used in route modules or directly with theuseSearchParamshook.searchParamsSchemaexport: A new, optional export from route modules. It holds the schema definition for that route's search parameters, created usingdefineSearchParams. This export serves as the canonical source for internal router processes (likeloaders/actions) to parse and typeURLSearchParamsfor their specific context.useSearchParamshook: The existing hook is updated. It now optionally accepts asearchParamsSchemaobject to provide type-safe access and updates to URL search parameters. If no schema is provided, it behaves as it currently does.Info.searchParamstype: A new property generated byreact-router typegenwithin a route'sInfotype, providing compile-time type safety for search parameters based on thesearchParamsSchemaexport.null. No errors are surfaced.Core Concepts
Dedicated
searchParamsSchemaRoute Module Export:A new, optional
searchParamsSchemaexport will be an object created by a React Router utility function, likedefineSearchParams({ param1: z.string(), param2: z.number() }). This declares the canonical types and validation rules for URL search parameters pertinent to this specific route. This export is crucial for internal router processes (such asloadersandactions) to consistently parse and typeURLSearchParamsfor their associated route's context.Internal Processing & Validation:
When a schema is provided to
useSearchParams(or used by other router internals), React Router's runtime internally parses and validatesrequest.url.searchParamsagainst the provided schema.null.setParams, any existing same-named parameters are overwritten by data conforming to the writer's schema.Type Generation Integration:
react-router typegenidentifies and processes thesearchParamsSchemaexport. It generates a correspondingsearchParamsproperty within the route'sInfotype (e.g., in.react-router/types/app/routes/+types/products.ts). This type will be based directly on the schema's inferred type (including potentialnullorundefinedtypes based on schema defaults).Example generated type snippet within
Info:Enhanced
useSearchParamsHook:The
useSearchParamshook is enhanced to:useSearchParams()), it returns the current untypedURLSearchParamsobject and updater.useSearchParams({ schema: mySchema })), it returns a tuple where the first element (params) is a strongly typed object based on the provided schema, and the second (setParams) accepts an object conforming to that schema for type-safe updates.searchParamsSchemaexported by the current route module, or any other schema defined elsewhere in the application.Example Implementation
app/routes/products.tsx:Advantages
useSearchParams()calls continue to work unchanged.searchParamsSchemaexport provides a canonical, typegen-discoverable schema for routes, crucial for consistent internal parsing inloaders/actions.Disadvantages / Trade-offs
useSearchParamsdoes not automatically infer thesearchParamsSchemafrom the module context; it must be explicitly provided. This trade-off provides the flexibility for the hook to be used with any schema, not solely restricted to the route's module definition.Community Alternatives
The React ecosystem has developed solutions to address the lack of type-safe URL search parameters, which this proposal builds upon and aims to integrate natively.
nuqs: A dedicated, type-safe search params state manager for React. This proposal is heavily inspired by
nuqs's declarative, parser-driven approach to managing URL state.Custom Hooks for Abstraction & Validation: A common pattern as described in an X post by Cory House involves creating custom React hooks that encapsulate
useSearchParams, abstracting away the manual parsing, validation (e.g., with Zod), and serialization logic. An example of this approach is shown in the following snippet:This proposal aims to bring the core benefits of these patterns directly into
useSearchParamsfor a more integrated and consistent first-party experience.Beta Was this translation helpful? Give feedback.
All reactions