react-use-query-params
v2.1.0
Published
Strongly typed, routing-library agnostic react hook to use and manipulate query params
Downloads
507
Maintainers
Readme
react-use-query-params
Strongly typed, routing-library agnostic react hook to use and manipulate query params.
Features
- Strongly Typed
- Uses Browser's DOM History API
- Functional Updates
- Re-renders only when the params you accessed changes.
Installation
# npm
npm install --save react-use-query-params
# pnpm
pnpm add react-use-query-params
Usage
Basic
Behaves very similar to React's useState
import useQueryParams from "react-use-query-params";
function App() {
const [params, setParams] = useQueryParams();
const clickHandler = () => {
setParams({
tomato: 'RED'
});
};
return (
<>
<div>
{params.tomato.length // parameters are always arrays of strings
? params.tomato[0]
: null}
</div>
<button onClick={clickHandler}>Update</button>
</>
);
}
Type Safety
If you don't want to accidentally access the wrong query param key, you can pass an object as the first generic type argument.
interface QueryParams {
tomato: string;
potato: string;
}
const [params, setParams] = useQueryParams<QueryParams>();
params.tomato; // ok
params.potato; // ok
params.mango; // Type Error
Multiple Values
You can send a string array in any key to setParams
setParams({
tomato: ['RED', 'ROUND']
});
Replace State
Sending true
as the second argument to setParams
will use .replaceState()
instead of .pushState()
setParams({
tomato: 'RED'
}, true);
Functional Updates (for Partial Updates)
Similar to React's useState
, you can pass a function to setParams
.
const [params, setParams] = useQueryParams<QueryParams>();
setParams((params) => {
return {
...params,
tomato: 'GREEN'
};
});
Behaviour
The params
object is actually a proxy that tracks which query params the rest of your code
is interested in. This allows the library to only trigger re-renders those parameters change.
The proxy also accounts for iteration (for (const key in params) { ... }
,
Object.keys(params)
, Object.values(params)
, etc). That means when you iterate
over the available keys, if a new query param is added, the component will re-render.
The same is true if the query param is removed even if you didn't access the param's value.
License
MIT