Product
Introducing Enhanced Alert Actions and Triage Functionality
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.
use-query-params
Advanced tools
Readme
A React Hook, HOC, and Render Props solution for managing state in URL query parameters with easy serialization.
Works with React Router and Reach Router out of the box. TypeScript supported.
Installation | Usage | Examples | API | Demo
When creating apps with easily shareable URLs, you often want to encode state as query parameters, but all query parameters must be encoded as strings. useQueryParams
allows you to easily encode and decode data of any type as query parameters with smart memoization to prevent creating unnecessary duplicate objects. It uses serialize-query-params.
Using npm:
$ npm install --save use-query-params
Link your routing system (e.g., React Router example, Reach Router example):
import React from 'react';
import ReactDOM from 'react-dom';
import { BrowserRouter as Router, Route } from 'react-router-dom';
import { QueryParamProvider } from 'use-query-params';
import App from './App';
ReactDOM.render(
<Router>
<QueryParamProvider ReactRouterRoute={Route}>
<App />
</QueryParamProvider>
</Router>,
document.getElementById('root')
);
Add the hook to your component. There are two options: useQueryParam
:
import * as React from 'react';
import { useQueryParam, NumberParam, StringParam } from 'use-query-params';
const UseQueryParamExample = () => {
// something like: ?x=123&foo=bar in the URL
const [num, setNum] = useQueryParam('x', NumberParam);
const [foo, setFoo] = useQueryParam('foo', StringParam);
return (
<div>
<h1>num is {num}</h1>
<button onClick={() => setNum(Math.random())}>Change</button>
<h1>foo is {foo}</h1>
<button onClick={() => setFoo(`str${Math.random()}`)}>Change</button>
</div>
);
};
export default UseQueryParamExample;
Or useQueryParams
:
import * as React from 'react';
import {
useQueryParams,
StringParam,
NumberParam,
ArrayParam,
} from 'use-query-params';
const UseQueryParamsExample = () => {
// something like: ?x=123&q=foo&filters=a&filters=b&filters=c in the URL
const [query, setQuery] = useQueryParams({
x: NumberParam,
q: StringParam,
filters: ArrayParam,
});
const { x: num, q: searchQuery, filters = [] } = query;
return (
<div>
<h1>num is {num}</h1>
<button onClick={() => setQuery({ x: Math.random() })}>Change</button>
<h1>searchQuery is {searchQuery}</h1>
<h1>There are {filters.length} filters active.</h1>
<button
onClick={() =>
setQuery(
{ x: Math.random(), filters: [...filters, 'foo'], q: 'bar' },
'push'
)
}
>
Change All
</button>
</div>
);
};
export default UseQueryParamsExample;
Or with the higher-order component (HOC) withQueryParams
:
import * as React from 'react';
import {
withQueryParams,
StringParam,
NumberParam,
ArrayParam,
} from 'use-query-params';
const WithQueryParamsExample = ({ query, setQuery }: any) => {
const { x: num, q: searchQuery, filters = [] } = query;
return (
<div>
<h1>num is {num}</h1>
<button onClick={() => setQuery({ x: Math.random() })}>Change</button>
<h1>searchQuery is {searchQuery}</h1>
<h1>There are {filters.length} filters active.</h1>
<button
onClick={() =>
setQuery(
{ x: Math.random(), filters: [...filters, 'foo'], q: 'bar' },
'push'
)
}
>
Change All
</button>
</div>
);
};
export default withQueryParams({
x: NumberParam,
q: StringParam,
filters: ArrayParam,
}, WithQueryParamsExample);
Or with render props via <QueryParams>
:
import * as React from 'react';
import {
QueryParams,
StringParam,
NumberParam,
ArrayParam,
} from 'use-query-params';
const RenderPropsExample = () => {
const queryConfig = {
x: NumberParam,
q: StringParam,
filters: ArrayParam,
};
return (
<div>
<QueryParams config={queryConfig}>
{({ query, setQuery }) => {
const { x: num, q: searchQuery, filters = [] } = query;
return (
<>
<h1>num is {num}</h1>
<button onClick={() => setQuery({ x: Math.random() })}>
Change
</button>
<h1>searchQuery is {searchQuery}</h1>
<h1>There are {filters.length} filters active.</h1>
<button
onClick={() =>
setQuery(
{
x: Math.random(),
filters: [...filters, 'foo'],
q: 'bar',
},
'push'
)
}
>
Change All
</button>
</>
);
}}
</QueryParams>
</div>
);
};
export default RenderPropsExample;
A few basic examples have been put together to demonstrate how useQueryParams
works with different routing systems.
For convenience, use-query-params exports all of the serialize-query-params library. This includes most functions from query-string, which is used internally.
The UrlUpdateType
is a string type definings the different methods for updating the URL:
'replaceIn'
: Replace just a single parameter, leaving the rest as is'replace'
: Replace all parameters with just those specified'pushIn'
: Push just a single parameter, leaving the rest as is (back button works)'push'
: Push all parameters with just those specified (back button works)See all param definitions from serialize-query-params here. You can define your own parameter types by creating an object with an encode
and a decode
function. See the existing definitions for examples.
Note that all nully values will encode and decode as undefined
.
Examples in this table assume query parameter named qp
.
Param | Type | Example Decoded | Example Encoded |
---|---|---|---|
StringParam | string | 'foo' | ?qp=foo |
NumberParam | number | 123 | ?qp=123 |
ObjectParam | { key: string } | { foo: 'bar', baz: 'zzz' } | ?qp=foo-bar_baz-zzz |
ArrayParam | string[] | ['a','b','c'] | ?qp=a&qp=b&qp=c |
JsonParam | any | { foo: 'bar' } | ?qp=%7B%22foo%22%3A%22bar%22%7D |
DateParam | Date | Date(2019, 2, 1) | ?qp=2019-03-01 |
BooleanParam | boolean | true | ?qp=1 |
NumericObjectParam | { key: number } | { foo: 1, bar: 2 } | ?qp=foo-1_bar-2 |
DelimitedArrayParam | string[] | ['a','b','c'] | ?qp=a_b_c' |
DelimitedNumericArrayParam | number[] | [1, 2, 3] | ?qp=1_2_3' |
Example
import { ArrayParam, useQueryParam, useQueryParams } from 'use-query-params';
// typically used with the hooks:
const [foo, setFoo] = useQueryParam('foo', ArrayParam);
// - OR -
const [query, setQuery] = useQueryParams({ foo: ArrayParam });
Example with Custom Param
You can define your own params if the ones shipped with this package don't work for you. There are included serialization utility functions to make this easier, but you can use whatever you like.
import {
encodeDelimitedArray,
decodeDelimitedArray
} from 'use-query-params';
/** Uses a comma to delimit entries. e.g. ['a', 'b'] => qp?=a,b */
const CommaArrayParam = {
encode: (array: string[] | null | undefined) =>
encodeDelimitedArray(array, ','),
decode: (arrayStr: string | string[] | null | undefined) =>
decodeDelimitedArray(arrayStr, ',')
};
useQueryParam<T>(name: string, paramConfig: QueryParamConfig<T>, rawQuery?: ParsedQuery):
[T | undefined, (newValue: T, updateType?: UrlUpdateType) => void]
Given a query param name and query parameter configuration { encode, decode }
return the decoded value and a setter for updating it.
The setter takes two arguments (newValue, updateType)
where updateType
is one of 'replace' | 'replaceIn' | 'push' | 'pushIn'
, defaulting to
'replaceIn'
.
You may optionally pass in a rawQuery object, otherwise the query is derived from the location available in the QueryParamContext.
Example
import { useQueryParam, NumberParam } from 'use-query-params';
// reads query parameter `foo` from the URL and stores its decoded numeric value
const [foo, setFoo] = useQueryParam('foo', NumberParam);
setFoo(500);
setFoo(123, 'push');
useQueryParams<QPCMap extends QueryParamConfigMap>(paramConfigMap: QPCMap):
[DecodedValueMap<QPCMap>, SetQuery<QPCMap>]
Given a query parameter configuration (mapping query param name to { encode, decode }
),
return an object with the decoded values and a setter for updating them.
The setter takes two arguments (newQuery, updateType)
where updateType
is one of 'replace' | 'replaceIn' | 'push' | 'pushIn'
, defaulting to
'replaceIn'
.
Example
import { useQueryParams, StringParam, NumberParam } from 'use-query-params';
// reads query parameters `foo` and `bar` from the URL and stores their decoded values
const [query, setQuery] = useQueryParams({ foo: NumberParam, bar: StringParam });
setQuery({ foo: 500 })
setQuery({ foo: 123, bar: 'zzz' }, 'push');
Example with Custom Parameter Type
Parameter types are just objects with { encode, decode }
functions. You can
provide your own if the provided ones don't work for your use case.
import { useQueryParams } from 'use-query-params';
const MyParam = {
encode(value) {
return `${value * 10000}`;
}
decode(strValue) {
return parseFloat(strValue) / 10000;
}
}
// ?foo=10000 -> query = { foo: 1 }
const [query, setQuery] = useQueryParams({ foo: MyParam });
// goes to ?foo=99000
setQuery({ foo: 99 })
withQueryParams<QPCMap extends QueryParamConfigMap, P extends InjectedQueryProps<QPCMap>>
(paramConfigMap: QPCMap, WrappedComponent: React.ComponentType<P>):
React.FC<Diff<P, InjectedQueryProps<QPCMap>>>
Given a query parameter configuration (mapping query param name to { encode, decode }
) and
a component, inject the props query
and setQuery
into the component based on the config.
The setter takes two arguments (newQuery, updateType)
where updateType
is one of 'replace' | 'replaceIn' | 'push' | 'pushIn'
, defaulting to
'replaceIn'
.
Example
import { withQueryParams, StringParam, NumberParam } from 'use-query-params';
const MyComponent = ({ query, setQuery, ...others }) => {
const { foo, bar } = query;
return <div>foo = {foo}, bar = {bar}</div>
}
// reads query parameters `foo` and `bar` from the URL and stores their decoded values
export default withQueryParams({ foo: NumberParam, bar: StringParam }, MyComponent);
<QueryParams config={{ foo: NumberParam }}>
{({ query, setQuery }) => <div>foo = {query.foo}</div>}
</QueryParams>
Given a query parameter configuration (mapping query param name to { encode, decode }
) and
a component, provide render props query
and setQuery
based on the config.
The setter takes two arguments (newQuery, updateType)
where updateType
is one of 'replace' | 'replaceIn' | 'push' | 'pushIn'
, defaulting to
'replaceIn'
.
encodeQueryParams<QPCMap extends QueryParamConfigMap>(
paramConfigMap: QPCMap,
query: Partial<DecodedValueMap<QPCMap>>
): EncodedQueryWithNulls
Convert the values in query to strings via the encode functions configured in paramConfigMap. This can be useful for constructing links using decoded query parameters.
Example
import { encodeQueryParams, NumberParam, stringify } from 'use-query-params';
// encode each parameter according to the configuration
const encodedQuery = encodeQueryParams({ foo: NumberParam }, { foo });
const link = `/?${stringify(encodedQuery)}`;
// Use one of these:
<QueryParamProvider ReactRouterRoute={Route}><App /></QueryParamProvider>
<QueryParamProvider reachHistory={globalHisory}><App /></QueryParamProvider>
<QueryParamProvider history={myCustomHistory}><App /></QueryParamProvider>
The QueryParamProvider component links your routing library's history to the useQueryParams hook. It is needed for the hook to be able to update the URL and have the rest of your app know about it.
See the tests or these examples for how to use it:
Example (Reach Router)
import React from 'react';
import ReactDOM from 'react-dom';
import { globalHistory, Router } from '@reach/router';
import { QueryParamProvider } from 'use-query-params';
import App from './App';
ReactDOM.render(
<QueryParamProvider reachHistory={globalHistory}>
<Router>
<App default />
</Router>
</QueryParamProvider>,
document.getElementById('root')
);
Run the typescript compiler in watch mode:
npm run dev
You can run an example app:
npm link
cd examples/react-router
npm install
npm link use-query-params
npm start
FAQs
React Hook for managing state in URL query parameters with easy serialization.
The npm package use-query-params receives a total of 233,602 weekly downloads. As such, use-query-params popularity was classified as popular.
We found that use-query-params demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.
Security News
Polyfill.io has been serving malware for months via its CDN, after the project's open source maintainer sold the service to a company based in China.
Security News
OpenSSF is warning open source maintainers to stay vigilant against reputation farming on GitHub, where users artificially inflate their status by manipulating interactions on closed issues and PRs.