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

[onyedikachi23]

RFC: Type-Safe URL Search Parameters for useSearchParams

Last Edited: June 3, 2025

This proposal is made according to the guidelines provided here: GOVERNANCE.md - New Feature Process.

---

Edit Summary

• API Refinement: useSearchParams now accepts schema via options object; defineSearchParams takes individual param schemas.
• Route Schema Renaming: searchParams export renamed to searchParamsSchema for router internals.
• Conflict Resolution: Defined independent parsing per route (value/default/null fallback); setParams overwrites.
• Type Generation: Enhanced typegen to infer Info.searchParams directly from route schemas.
• Core Justification: Added rationale for first-class API status (typegen, data flow, standardization).

---

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?

[rossipedia]

To add:

• How are search params from multiple matching routes resolved/merged?
• What happens when two routes export conflicting types for search params?

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

[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?