Validating URL search parameters in React often starts with the same small chore: read window.location.search, convert a value such as page into a number, and choose a fallback for something like q. As that code spreads across components, malformed-value handling can become repetitive and inconsistent. Lei Wang built @standard-search-params/react to centralize that work while accepting validators through Standard Schema, rather than tying the hook to one validation library.
Why use Standard Schema for a React search-parameter hook?
Existing libraries already address typed URL parameters. Wang’s design choice is to let the hook accept validators that implement the Standard Schema interface, so callers can use compatible validators from different libraries rather than a Zod-specific integration. The package README names Zod v3.24 or later, Zod v4, Valibot, and ArkType as examples. The package README and Wang’s September 21, 2026 article describe this rationale.
Instead of passing one composed object schema, callers provide a plain object that maps each query key to its own validator:
{ page: z.coerce.number().int().min(1), q: z.string().min(1) }This keeps the hook’s work field-by-field. Standard Schema provides a common validator interface, but does not define a library-independent way for the hook to extract individual field validators from an object schema. A key-to-validator map also avoids relying on library-specific operations such as Zod’s .pick() or Valibot’s .entries.
Recommended Free Tools
#1 Best Overall
What happens when a query parameter is invalid?
The hook returns two views of the URL values: searchParams contains raw strings, while validatedSearchParams contains successfully parsed values. Given ?page=2&q=hello&sort=bad and validators for page and q, the validated result includes page: 2 and q: 'hello'. The sort parameter is not part of that result because no validator was provided for it.
If a key has a validator but its value is missing or malformed, that field is omitted from the validated result; other fields that pass validation remain. The README puts the intended behavior this way: “One invalid param never throws away the rest.” This describes the documented per-field behavior, not an independent test result. Only keys in the validator map are read. Even a value intended to pass through unchanged needs a validator, such as a schema that accepts any string.
When does the hook read the URL?
The hook reads window.location.search after the component mounts in the browser. It is not a way to validate query parameters for the initial server-rendered HTML. In server-side rendering, the documented behavior is for both the initial server render and the initial client render to remain not-ready until the client effect reads and validates the URL. That avoids accessing window during server rendering, but means the UI may need a brief loading or not-ready state.
If a page needs validated values in its server-rendered output, validate the parameter object available on the server directly rather than relying on this hook for that first render.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
How does it stay current during navigation?
By default, the hook reads the URL once on mount. The README for package version 0.2.0 documents optional browser back/forward listening through { listenToPopstate: true }. When enabled, this responds to the browser’s popstate event.
Client-side router pushes and navigations generally do not emit popstate. For those transitions, the caller must connect the router’s location change to the hook’s refresh() function. Repeated refreshes with an unchanged search string are skipped unless refresh is forced. The hook therefore does not automatically subscribe to every SPA router’s navigation state.
What validation constraints should you account for?
- Validation is synchronous. A validator that returns a Promise is treated as invalid, and the package documentation says a development warning is issued.
- Validation is per field. Cross-field checks defined on a composed object schema are not applied by this key-by-key API.
- The set of keys is fixed from the initial render. The documentation says to remount the hook if the key set genuinely changes; a development warning identifies this situation.
These choices keep the hook focused on synchronous parsing of individual URL values. They also mean it is not a substitute for object-level validation when fields must satisfy rules together, or for asynchronous checks.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.When is this approach a good fit?
It is a fit when a component needs parsed query values, field failures should not erase unrelated valid values, and the application can refresh the hook when its router changes the URL. Standard Schema is useful when a codebase wants the same hook API to work with compatible validators from more than one library.
Best Value
Choose a different approach if the initial server-rendered output must contain validated query values, if correctness depends on cross-field or asynchronous validation, or if you need navigation updates to be managed automatically by your router integration. The package documents its peer requirement as “react (>=16.8) is the only peer dependency” for the listed version 0.2.0. That is the package’s stated dependency requirement, not a claim about every supported React application setup.
Wang summarizes the design preference in Japanese: “機能を積み増すより、「挙動が予測できる」ことを優先して作っています。” In context, he says he prioritizes predictable behavior over continually adding features. The documented boundaries—post-mount browser reads, per-key synchronous validation, and explicit refresh integration—are important parts of that tradeoff.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
