A React Hook to use URL query string as a state management
useUrlSearchParams()
A React Hook to use URL query string as a state management
npm install use-url-search-params
or
yarn add use-url-search-params
For most of the time you will do something like this:
import React from "react";
import { useUrlSearchParams } from "use-url-search-params";
function App() {
// Your page URL will be like this by default: http://my.page?checked=true
const [params, setParams] = useUrlSearchParams({ checked: true });
React.useEffect(() => {
// do something when `params.checked` is updated.
}, [params.checked]);
return (
<div>
<input type="checkbox" checked={params.checked} onChange={(e) => setParams({ checked: e.target.checked })} />
</div>
);
}
By default, all values parsed from URL query are string. In case you want to get boolean or number value, pass a second argument to useUrlSearchParams()
to specify data type you want to get from params
object. Here is an example:
const initial = {
y: "option1",
};
const types = {
x: Number,
y: Boolean,
z: Date,
t: ["option1", "option2", "option3"],
};
const [params, setParams] = useUrlSearchParams(initial, types);
// `params.x` will be number (or NaN)
// `params.y` will be one of [undefined, true, false]
// `params.z` will be instance of Date (can be Invalid Date)
// `params.t` will be one of ["option1", "option2", "option3"] (can be `undefined` if not specified in `initial`)
Although you can use JSON.parse()
and JSON.stringify()
to get/set arbitrary serializable data to URL query, it is not recommended. URL query is a good place to store and persist page settings as key/value pairs such as table filter, sorting, paging, etc. We should keep it that way for simplicity. For complex data structure, you should consider using other state management for better performance, security and flexibility.
WARNING: Be aware of XSS attack. Be careful to validate values from URL query before using it by either using
types
- the second parameter passed touseUrlSearchParams()
or validate them yourself if neccessary.
But if you still insist, here is an example:
function App() {
const [params, setParams] = useUrlSearchParams(
{},
{
complexData: (dataString) => {
try {
return JSON.parse(dataString);
} catch (e) {
return {};
}
},
}
);
const onSetParams = (data) => {
setParams({ complexData: JSON.stringify(data) });
};
return <div>{/*...*/}</div>;
}
Should just work with React Router or any routing system. Just make sure that your component re-render whenever route changes.
initial
(optional | Object): To set default values for URL query string.types
(optional | Object): Has similar shape with initial
, help to resolve values from URL query string. Supported types:
String
(default)Number
Bool
Date
- Date.prototype.toISOString()
is used to parse date to string, e.g date string in your URL query is zero UTC offsetreplace
(optional | boolean | default: false): If true, will call histor#replaceState()
instead of history#pushState()
on url search param change.This library is built base on URLSearchParams interface
MIT