Search Params
Read and write URLSearchParams with full type-safety using @search-params/react using any React Framework and any schema validation library.
Documentation
For usage development reference the project's readme.md for more detailed information.
Introduction
This project is heavily inspired by TanStack's Router Search Params with the exception that (a) it isn't limited to a specific React framework and (b) it reads and writes Search Params using the same hook.
Why Search Params?
The URL Search Params is perfectly able to act as a form of global state. If you would like to know more about this, give TanStack's Router Search Params, the "OG" State Manager a read.
Getting Started
1. Set up the provider
Use SearchParamsProvider and pass in (a) the URL query (URLSearchParams or string) and (b) router methods from your framework of choice. This provider allows @search-params/react to read and write Search Params with any React framework. The example below is using Next.
Type Declaration SearchParamsProvider
type SearchParamsProviderProps = {
query: URLSearchParams | string;
router: {
push: (href: string, options?: { scroll: boolean }) => void;
replace: (href: string) => void;
};
};"use client";
import * as React from "react";
import { useRouter, useSearchParams } from "next/navigation";
import { SearchParamsProvider } from "@search-params/react";
export const Providers: React.FC<React.PropsWithChildren> = ({ children }) => {
const router = useRouter();
const searchParams = useSearchParams();
return (
<SearchParamsProvider query={searchParams} router={router}>
{children}
</SearchParamsProvider>
);
};2. Set up your schema validations
Use createSearchParamsConfig to create a config object to handle all validations. You can choose any schema validation library (i.e. Valibot, Zod, Yup, etc..), or write your own, to handle your validations.
import { createSearchParamsConfig } from "@search-params/react";
import { fallback, number, object, parse, string, optional } from "valibot";
const searchParamsSchema = object({
page: fallback(number([minValue(1)]), 1),
item: fallback(optional(string()), undefined),
});
export const config = createSearchParamsConfig({
home: (search) => parse(searchParamsSchema, search),
});Usage
Type Declaration useSearchParams
type UseSearchParams<TSearchParams> = TSearchParams {
setQuery: (
input:
| Partial<TSearchParams>
| ((prevParams: TSearchParams) => Partial<TSearchParams>),
options?: { scroll: boolean }
) => void;
clearQuery: (options?: { scroll: boolean }) => void;
};Read Search Params
Pass your route's config / schema validator as your function's argument.
"use client";
import * as React from "react";
import { useSearchParams } from "@search-params/react";
import { config } from "./config";
export default function Home() {
const { page, item } = useSearchParams({
// ˄ page: number;
// ˄ item: string | undefined;
route: config.home,
});
}Set Search Params
Supports functional updates and scrolling (if your router supports it).
"use client";
import * as React from "react";
import { useSearchParams } from "@search-params/react";
import { config } from "./config";
export default function Home() {
const { setQuery } = useSearchParams({
route: config.home,
});
return (
<div>
<Input
type="text"
onChange={(e) =>
setQuery({
item: e.currentTarget.value,
})
}
/>
<button
onClick={() =>
setQuery(({ page }) => ({
page: page + 1,
}))
}
>
Add +1
</button>
</div>
);
}Clear Search Params
Supports scrolling if your router supports it.
"use client";
import * as React from "react";
import { useSearchParams } from "@search-params/react";
import { config } from "./config";
export default function Home() {
const { clearQuery } = useSearchParams({
route: config.home,
});
return (
<button onClick={() => clearQuery({ scroll: true })}>
Clear Search Params
</button>
);
}Feedback or Issues
Please create an issue using GitHub Issues