[RFC]: Type-Safe URL Search Params for useSearchParams hook

[onyedikachi23]

RFC: Type-Safe URL Search Parameters for useSearchParams

Last 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

useSearchParams currently exposes the untyped URLSearchParams API. 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 useSearchParams to the same standard of type safety as other core React Router APIs. By integrating a standard schema-based approach for search params, we can:

• Improve Reliability: Reduce runtime errors via compile-time validation.
• Boost Productivity: Eliminate boilerplate, provide autocompletion, and simplify refactoring.
• Achieve Consistency: Harmonize useSearchParams with the library's existing type system.
• Leverage Standard Tooling: Utilize the robust parsing and validation capabilities inherent in standard schemas (e.g., zod).
• Essential Core Integration: This functionality needs to be part of the React Router core because its full benefits, including automatic type generation (typegen), seamless type consistency for loaders and actions, 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 searchParamsSchema Route Module Export & Enhanced useSearchParams Hook

We propose introducing a new, optional searchParamsSchema export 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 typegen would process this to type the route's Info object. Concurrently, the useSearchParams hook will be enhanced to accept an optional schema, providing typed state when a schema is provided, while maintaining backward compatibility by returning an untyped URLSearchParams object when no schema is passed.

New Utilities and Concepts

• defineSearchParams utility: 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 the useSearchParams hook.
• searchParamsSchema export: A new, optional export from route modules. It holds the schema definition for that route's search parameters, created using defineSearchParams. This export serves as the canonical source for internal router processes (like loaders/actions) to parse and type URLSearchParams for their specific context.
• Enhanced useSearchParams hook: The existing hook is updated. It now optionally accepts a searchParamsSchema object to provide type-safe access and updates to URL search parameters. If no schema is provided, it behaves as it currently does.
• Info.searchParams type: A new property generated by react-router typegen within a route's Info type, providing compile-time type safety for search parameters based on the searchParamsSchema export.
• Prioritized Parameter Parsing: A specific parsing logic for each parameter: return parsed value if valid, else schema's default, else null. No errors are surfaced.

Core Concepts

1. Dedicated searchParamsSchema Route Module Export:
   A new, optional searchParamsSchema export will be an object created by a React Router utility function, like defineSearchParams({ 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 as loaders and actions) to consistently parse and type URLSearchParams for their associated route's context.

2. Internal Processing & Validation:
   When a schema is provided to useSearchParams (or used by other router internals), React Router's runtime internally parses and validates request.url.searchParams against the provided schema.

   • Parsing Logic: For each parameter: The parsed value is returned if its URL value successfully conforms to the schema. Otherwise, the schema's default value is returned if provided. Otherwise, the value for that parameter will be null.
   • No parsing errors are surfaced directly.
   • Conflict Resolution (Reads): The parsing logic is applied independently for each parameter based on the specific schema in use. There is no merging or complex resolution of schemas across routes. Parameters not in the schema being used are ignored.
   • Conflict Resolution (Writes): When writing via setParams, any existing same-named parameters are overwritten by data conforming to the writer's schema.

3. Type Generation Integration:
   react-router typegen identifies and processes the searchParamsSchema export. It generates a corresponding searchParams property within the route's Info type (e.g., in .react-router/types/app/routes/+types/products.ts). This type will be based directly on the schema's inferred type (including potential null or undefined types based on schema defaults).

   Example generated type snippet within Info:

   // ...
   export type Info = {
       // ... existing properties
       params: {} & { [key: string]: string | undefined };
       searchParams: {
           // Type inferred from the schema
           query: string;
           page: number | null;
           category?: string[];
       };
       // ... other existing properties (loaderData, actionData, etc.)
   };
   // ...

4. Enhanced useSearchParams Hook:
   The useSearchParams hook is enhanced to:

   • Backward Compatibility: When called without a schema argument (useSearchParams()), it returns the current untyped URLSearchParams object and updater.
   • Optional Type Safety: When called with a schema argument (e.g., 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.
   • Flexible Schema Source: The schema provided to the hook can be the searchParamsSchema exported by the current route module, or any other schema defined elsewhere in the application.

Example Implementation

app/routes/products.tsx:

import { useSearchParams, defineSearchParams } from "react-router";
import type { Route } from "./+types/products";
import { z } from "zod";

export const searchParamsSchema = defineSearchParams({
  query: z.string().optional().default(""), // 'query' will always be a string
  page: z.preprocess(
    (a) => parseInt(z.string().parse(a), 10),
    z.number().int().min(1)
  ).optional(), // 'page' can be number, null, or undefined
  category: z.array(z.string()).optional(), // 'category' can be string[] or undefined
});

export default function ProductsPage({ searchParams }: Route.ComponentProps) {
  // Using the route's defined schema for type-safe access
  const [params, setParams] = useSearchParams({ schema: searchParamsSchema });

  const handlePageChange = (newPage: number) => {
    // setParams provides type-safe updates based on the schema
    setParams({ ...params, page: newPage });
  };

  return (
    <div>
      <h1>Products</h1>
      <p>Current Page: {params.page ?? "Not provided or invalid"}</p>
      <button onClick={() => handlePageChange((params.page || 0) + 1)}>
        Next Page
      </button>
    </div>
  );
}

const MyUntypedComponent = () => {
  // Hook usage without a schema remains untyped for backward compatibility
  const [urlSearchParams, setUrlSearchParams] = useSearchParams();
  const rawQuery = urlSearchParams.get("q");
  return <div>Raw Query: {rawQuery}</div>;
};

const adHocSearchSchema = defineSearchParams({
    searchTerm: z.string().default(""),
});

const AdHocSearchComponent = () => {
  // Hook usage with an ad-hoc schema, not from a route module
  const [search, setSearch] = useSearchParams({ schema: adHocSearchSchema });
  return <div>Ad-hoc Search Term: {search.searchTerm}</div>;
};

---

Advantages

• Non-Breaking Backward Compatibility: Existing useSearchParams() calls continue to work unchanged.
• Flexible Opt-in Type Safety: Developers choose when and where to apply schema-based type safety, using any schema.
• Native Route Integration (Optional): The searchParamsSchema export provides a canonical, typegen-discoverable schema for routes, crucial for consistent internal parsing in loaders/actions.
• Complete Type Safety (When Opted-in): Provides compile-time and runtime validation for URL search params with predictable null/default fallbacks.
• Reduced Boilerplate: Eliminates manual parsing/validation in components when opting into schemas.
• Enhanced Developer Experience: Improves autocompletion, refactoring, and code readability.

---

Disadvantages / Trade-offs

• Increased Bundle Size: Requires integrating standard schema validation, potentially increasing core bundle size.
• Explicit Schema Passing: useSearchParams does not automatically infer the searchParamsSchema from 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:

  import { useSearchParams } from "react-router";
  import { z } from "zod";
  import { useCallback, useMemo } from "react";
  
  const productSearchParamsSchema = z.object({
      name: z.string(),
      size: z.enum(["small", "medium", "large"]),
  });
  
  export const useProductSearchParams = () => {
      const [searchParams, setSearchParams] = useSearchParams();
  
      const { name, size } = useMemo(() => {
          return productSearchParamsSchema.parse({
              name: searchParams.get("name")?.toLowerCase() ?? "",
              size: searchParams.get("size") ?? "",
          });
      }, [searchParams]);
  
      const setParam = useCallback(
          (paramName: string, paramValue: string) => {
              const newSearchParams = new URLSearchParams(searchParams);
              if (paramValue) {
                  newSearchParams.set(paramName, paramValue);
              } else {
                  newSearchParams.delete(paramName);
              }
              setSearchParams(newSearchParams);
          },
          [searchParams, setSearchParams]
      );
  
      return useMemo(
          () => ({
              name,
              size,
              setName: (name: string) => setParam("name", name),
              setSize: (size: string) => setParam("size", size),
          }),
          [name, size, setParam]
      );
  };

This proposal aims to bring the core benefits of these patterns directly into useSearchParams for a more integrated and consistent first-party experience.

[alexanderson1993]

A few questions:

• Why is searchParams exported from the route, but also passed as a prop to the route component? Seems a little redundant.
• This proposal recommends using a validation library. What happens when search params are passed that fail validation?
• Why use a validation library when a type annotation would be enough for type safety?
• What is preventing this from being a user land React hook that generically wraps useSearchParams?
• Finally, how does this relate specifically to the "Routing and Data Focused" design goal, specifically "avoid adding first class APIs that can be implemented in user-land"? Why does this need to be part of the React Router core?

[onyedikachi23]

A few questions:

* Why is `searchParams` exported from the route, but also passed as a prop to the route component? Seems a little redundant.

* This proposal recommends using a validation library. What happens when search params are passed that fail validation?

* Why use a validation library when a type annotation would be enough for type safety?

* What is preventing this from being a user land React hook that generically wraps `useSearchParams`?

* Finally, how does this relate specifically to the "Routing and Data Focused" design goal, specifically "avoid adding first class APIs that can be implemented in user-land"? Why does this need to be part of the React Router core?

I've updated the RFC to address these concerns. And here's a summarized reply:

Here are the replies to your questions:

• The exported searchParamsSchema defines types for router tools and internal processes. The searchParams prop is the actual parsed data for your component.
• If search parameters fail validation, they fall back to a schema's default value or become null without erroring.
• Type annotations ensure correctness during development. A validation library checks real-world URL data at runtime to ensure it matches expected types.
• Core integration allows for automatic type generation (typegen), consistent typing for loaders/actions, and a standardized API, which is difficult to achieve reliably in user-land.
• This deep integration aligns with the "Routing and Data Focused" goal, as it provides unique benefits (like typegen and unified data flow) that can't be cleanly achieved solely in user-land.

[onyedikachi23]

To add:

* How are search params from multiple matching routes resolved/merged?

* What happens when two routes export conflicting types for search params?

Thanks for mentioning these @rossipedia. These your concerns highlighted major problems with the proposal, which I've updated. Here's the summary:

• Search parameters from multiple matching routes are not resolved or merged. Each route's searchParamsSchema independently parses the URL for its own context, ignoring parameters not defined in its schema.
• When two routes export conflicting types for search parameters, it's handled by their independent parsing. Each route processes the URL against its own schema, so conflicts only affect the typing and parsing within that specific route.

[alexanderson1993]

I'll note that search params are also often used in loader and action. For a complete proposal, you should include examples of how that would work. I would argue that a parseUrlSearchParams(request.url, schema) that is run in loaders or actions would be possible to implement in user land, and therefore this proposal is unnecessary.

Also

What I don't understand is why I both need to export the schema from the route AND pass the schema into useSearchParams, as. you are doing here:

  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

A validation library checks real-world URL data at runtime to ensure it matches expected types.

Seems to conflict with this answer

if search parameters fail validation, they fall back to a schema's default value or become null without erroring.

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

When two routes export conflicting types for search parameters, it's handled by their independent parsing.

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.

[rossipedia]

I think I'm still landing on this:

avoid adding first class APIs that can be implemented in user-land

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 react-router developer having to pull down the code for this if they don't need it. The presence of nuqs and the like, or just using a basic zod schema, are fairly strong indicators that this can be implemented quickly and directly in user-land. Even with zod, most use-cases are incredibly simple:

const { searchParams } = new URL(request.url);
const typedParams = z.object({ ... })
  .parse(Object.fromEntries(searchParams))
  .catch({
    // default values
  });

[onyedikachi23]

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.

— Tanner Linsley

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.

[moishinetzer]

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.

• What should happen when params that are not defined/allowed are passed in.
• How can params be programmatically added to without requiring them upfront as is often the case with URLSearchParams
• How should search params be consumed within a component. Is a hook the right choice? (My intuition says no)
• How is the Form method="GET" handled so that it is typesafe there as well?

[onyedikachi23]

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.

[grz-gajda]

I have some thoughts about implementing type-safety searchParams into react-router though I chose a slightly different approach.

1. New route's function validateSearchParams:

export function validateSearchParams<T>(search: URLSearchParams): T;

It won't require any library (zod, valibot, etc). It won't be standard-schema compliant by default. We should leave it to developers. Default approach still shoul be possible:

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 zod/valibot:

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))
}

2. validateSearchParams should happen before loader/action.

The flow of execution should look like that:

Server: validateSearchParams -> loader (or action) -> Component
Client: validateSearchParams -> clientLoader (or clientAction) -> Component

Thanks to that we can set new property in Route.LoaderArgs, Route.ActionArgs and Route.ComponentProps.

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>
}

3. Validation should have boundaries for that one route.

|_ `index.tsx` <- has `?sidebar`
  |_ `users.tsx` <- has nothing
    |_ `users.$id.tsx` <- has `?filter`

In that case users.$id.tsx shouldn't have passed ?sidebar as an argument. Though it can parse it by itself. Because validateSearchParams are plain Javascript functions it's possible to compose them.

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' }
  }
}

4. With three first points we validated and passed searchParams from URL to loader, action and Component. Last step is change its state. I recommend to build utility function similar to href:

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 'users/:id'. Current href type definition is:

export function href<Path extends keyof Args>(
  path: Path,
  ...args: Args[Path]
): string

If 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 href utility:

import { Link } from 'react-router'


<Link to={href('/users/:id', { id: '1' }, { filter: {} })} />
// or
<Link to={href('/users/:id', { id: '1' }, prev => ({ ...prev, filter: {} }) } />

prev in href utility will be ReturnType<typeof Route.validateSearchParams>. Yes, if we do not define parent's search params, prev function should remove them on change. It is something the developer should remember.

5. Hooks. I prefer to leave useSearchParams as it is, untyped.

6. When validateSearchParams would fail (throw an error), page should render the closest <ErrorBoundary />. Same approach as when loader/action fails.

[grz-gajda]

I have a short disclaimer for my suggestions.

---

URLSearchParams: parsing and serialization

I 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 ?name=lorem&email=ipsum or even more complicated like ?name=lorem&roles=admin:user:banned. You see admin:user:banned? With that function we have to make:

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 roles every time when they want to use (from [admin, user, banned] into admin:user:banned) and even then the types won't match (string vs string[]).

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 and type Serializer are just simple function types what we receive and what we expect to get.

defaultSerializer is default way for searchParams serialization. Default serializer should use JSON.stringify because it's easy and Tanner do something similar in TanStack Router.

defineSearchParams is helper utility to have same types. Route's Module should require searchParams to have signature

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 searchParams.serializer with href or anything.

---

Timing

Recently 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 URLSearchParams. It's accessible from every place in React's tree, somehow maintanable and shareable between users. Though I wouldn't like searchParams to become state as a state. Still, it's a part of URL and we should treat it as an URL. That's why I am opposite to using or extending useSearchParams or any kind of similar hooks.

Every "save" action (that change the state) should require real change action, like clicking the <Button /> with <Form method='GET' /> or just clicking regular <Link /> with additional search params. There was even a discussion about that, you can find it here: #8908. By sticking to current behavior (consider changing "state" as a navigation) I think we shouldn't have problem with timing or anything like that. I'm aware that the feature will look less useful for some of devs and we will have to make a big exclamation mark in the docs about that but it's still the safest way to implement that feature, I guess.

Same suggestion I have for shallow option from nuqs. That option is described here. As I like nuqs library, I don't think we should go the same way.

[AlemTuzlak]

FWIW this proposal + Sergios suggestion is the way I'd go with this as well, I literally came in to write the same pseudo-code when I saw this. I think the serilization and deserialization should be handled in user-land, the only thing that could belong to react-router is the added properties and typesafety on top.

[franky47]

In the Zod 4.1 release, codecs were introduced to add (de)serialisation primitives to the existing runtime validation APIs. Since other validation libraires already support this too (Effect, io-ts), it's only a matter of time before a unifying interface like Standard Schema becomes available for bidirectional conversions between strings and rich data types.

Such an interface could inherit from Standard Schema, or be a different interface altogether: https://x.com/ethanniser/status/1959716030890299570

[onyedikachi23]

@AlemTuzlak I love nuqs mostly because I don't have to worry about serialization/deserialization. Just like Tanstack Router, a decent support would be great. At most, I rarely have to use query values with complex structures.

[onyedikachi23]

In the Zod 4.1 release, codecs were introduced to add (de)serialisation primitives to the existing runtime validation APIs. Since other validation libraires already support this too (Effect, io-ts), it's only a matter of time before a unifying interface like Standard Schema becomes available for bidirectional conversions between strings and rich data types.

Such an interface could inherit from Standard Schema, or be a different interface altogether: https://x.com/ethanniser/status/1959716030890299570

I vouch for this. But since it's not yet supported on Standard Schema, it'd be an afterthought.

[remorses]

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 function:

href('/city', { searchParam1: 'x' })

You get type safe search params in components routes:

export default function Page({ params: { searchParam1 }: Route.ComponentProps }) {
  // ...
}

[onyedikachi23]

This way you also have type safe href function:

href('/city', { searchParam1: 'x' })

You get type safe search params in components routes:

export default function Page({ params: { searchParam1 }: Route.ComponentProps }) {
  // ...
}

Take a look at this comment.
The 4th point aligns with your suggestion for the href util, and I also agree with @moishinetzer's idea for the search to be only in the object param. I think this concretes how the href API should be.

However, I'd still prefer leaving the routes.ts file simple as is, because the points from that comment still allows for:

Rather than just an object this could take a zod schema (or any open schema for that matter) and it can be used for runtime validation too to ensure no bad actors can use those params viciously.

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 /product route in products.tsx, still have to come over in routes.ts file, just to add search params definition.

[grz-gajda]

I think there are problems with that approach.

1. There is react-router/fs-routes package (95k weekly downloads at the moment) that will lose access to that feature. With configuration at route level, they still will have that feature.

2. In data mode you can define loader/action properties though you don't have routes.ts file (index, route, etc functions). That means with your approach we lose possibility to add searchParam property and with approach from that comment it still be possible.

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 (routes.ts in framework mode and createBrowserRouter in data mode).

[remorses]

There is react-router/fs-routes package (95k weekly downloads at the moment) that will lose access to that feature. With configuration at route level, they still will have that feature.

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
})

In data mode you can define loader/action properties though you don't have routes.ts file

That's to be expected. href and other routes type safety are enabled only in framework mode.

[grz-gajda]

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 validateSearchParams and result of that should be passed to loader and Component as a prop. I think it's even possible to add type inference and make search typed based on validateSearchParams.

Maybe there's a problem with RFC's name or I don't understand something. I don't think about type-safety as const a = new URLSearchParams() as MyTypedUser because it's not about that. I would like to have real type safety like URLSearchParams casted into another object. Then I don't care about it's type, casting guarantees that I know on what I am working on. That's why I'm against putting it into routes.ts, it should be available also in different modes.

[onyedikachi23]

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 useSearchParams hook, as explicitly stated in the title.

I really see light in the suggestions from @grz-gajda, but @remorses, if there are other valid reasons you're pushing for the routes.ts (except for the fs-routes), it'd be a favourable contribution to make.

[remorses]

I opened a separate RFC for adding the search params in the routes.ts file, please upvote that RFC if you prefer that approach

#13800