use-url-search-params
v2.5.1
Published
[![GitHub license](https://img.shields.io/github/license/Naereen/StrapDown.js.svg)](https://github.com/rudyhuynh/use-url-search-params/blob/master/License)
Downloads
14,056
Maintainers
Readme
useUrlSearchParams()
A React Hook to use URL query string as a state management
Why you need this
- Your app need to persist its state after user refresh the page (used for simple, non-sensitive data).
- Some page settings (ex: table filter, sorting, paging, etc.) should be saved in the URL so that user can easily pass to others. e.g. Tester can easily send a URL of a page to developer with very least reproduce steps.
- You want to do something (request new data, etc.) every time some URL query value changes.
- Combine all of the above with a URL query as a single source of truth.
Installation
npm install use-url-search-params
or
yarn add use-url-search-params
How to use
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>
);
}
How to control the value parsed from URL query
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`)
Complex data structure
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>;
}
React Router
Should just work with React Router or any routing system. Just make sure that your component re-render whenever route changes.
API
- useUrlSearchParams([initial, types, replace])
initial
(optional | Object): To set default values for URL query string.types
(optional | Object): Has similar shape withinitial
, 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 offset- Array of available string values (like enum)
- A custom resolver function
replace
(optional | boolean | default: false): If true, will callhistor#replaceState()
instead ofhistory#pushState()
on url search param change.
Read more (for maintainers)
This library is built base on URLSearchParams interface
License
MIT