React Hook for managing state in URL query parameters with easy serialization.
ISC License
Published by pbeshai over 1 year ago
Published by pbeshai about 2 years ago
Published by pbeshai about 2 years ago
skipUpdateWhenNoChange
defaults to true (set to false for previous behavior)Published by pbeshai about 2 years ago
Published by pbeshai about 2 years ago
Breaking
null
. You can continue using query-string by specifying the searchStringToObject
and objectToSearchString
options as parse and stringify respectively.New Features
Deep imports for React-Router 5 and 6 adapters
Supports registering params in the QueryParamProvider to have them available to any downstream hooks.
Additional function signatures have been added, but greater care must be taken to get proper types out of the response.
useQueryParam(’myparam’)
← param type is inherited from the params registered in the QueryParamProvider
useQueryParam(’myparam’, StringParam, options)
useQueryParams()
← gets all params from the QueryParamProvider
useQueryParams([’myparam1’, ‘myparam2’])
← gets just myparam1 and myparam2 from those registered in the QueryParamProvider.useQueryParams({ myparam: StringParam }, options)
useQueryParams({ myparam: ‘inherit’ }, options)
←inherit myparam param name from QueryParamProvider
New options
prop to QueryParamProvider and argument to useQueryParam(s)
enableBatching
option (i.e., multiple consecutive calls to setQueryParams in a row only result in a single update to the URL). This seems to work but would require updating the way all the tests are written to verify for sure, so marking as experimental for now.removeDefaultsFromUrl
(default: false). This happens on updates only, not on initial load. Requires the use of the default
attribute on a parameter to function (note serialize-query-params v2 withDefault now populates this).includeKnownParams
- in addition to those specified, also include all preconfigured parameters from the QueryParamProvider
includeAllParams
(default: false) - in addition to those specified, include all other parameters found in the current URLupdateType
(default “pushIn”) - the default update type when set is called.searchStringToObject, objectToSearchString
(default uses URLSearchParams) - equivalent of parse
and stringify
from query-string.Parameters now can include urlName
to automatically convert to a different name in the URL (e.g. { encode, decode, urlName })
Caches decoded values across multiple hook calls from different components
Fixes
Stops reading from refs in render to prepare for future versions of React where this is not allowed.
Simplifies the way locations are updated by only passing in the search string as the new location.
v2.0.0-rc.1 Fix CJS imports of adapters (#224)
v2.0.0-rc.1 Be more defensive about reading updateType
There are two things you need to adjust to update from v1:
searchStringToObject
and objectToSearchString
.Here's an example of the changes to complete both for React Router 5:
import React from 'react';
import ReactDOM from 'react-dom';
import { QueryParamProvider } from 'use-query-params';
+ import { ReactRouter5Adapter } from 'use-query-params/adapters/react-router-5';
+ import { parse, stringify } from 'query-string';
- import { BrowserRouter as Router, Route } from 'react-router-dom';
+ import { BrowserRouter as Router } from 'react-router-dom';
import App from './App';
ReactDOM.render(
<Router>
- <QueryParamProvider ReactRouterRoute={Route}>
+ <QueryParamProvider
+ adapter={ReactRouter5Adapter}
+ options={{
+ searchStringToObject: parse,
+ objectToSearchString: stringify,
+ }}
+ >
<App />
</QueryParamProvider>
</Router>,
document.getElementById('root')
);
If you're using react-router-6, you'd import that adapter instead:
import { ReactRouter6Adapter } from 'use-query-params/adapters/react-router-6';
Note the options
above are optional, but will retain the behavior you're used to from v1, which used query-string internally. If you want to switch to using URLSearchParams and not use query-string, you would do:
import React from 'react';
import ReactDOM from 'react-dom';
import { QueryParamProvider } from 'use-query-params';
+ import { ReactRouter5Adapter } from 'use-query-params/adapters/react-router-5';
- import { BrowserRouter as Router, Route } from 'react-router-dom';
+ import { BrowserRouter as Router } from 'react-router-dom';
import App from './App';
ReactDOM.render(
<Router>
- <QueryParamProvider ReactRouterRoute={Route}>
+ <QueryParamProvider adapter={ReactRouter5Adapter}>
<App />
</QueryParamProvider>
</Router>,
document.getElementById('root')
);
This update just provides better error messages for common issues new users encounter:
Updates to serialize-query-params v1.0.1
foo = null
-> ?foo
, foo = ''
-> ?foo=
, foo = undefined
-> ?
(removes if present--this was current behavior)const { foo = [] } = query
won't work when foo = null). To get around this, a withDefault helper has been added.useQueryParams({ foo: withDefault(ArrayParam, []) })
#76 Switches default update type from replaceIn to pushIn
{ foo: '' }
will now serialize as foo-
and deserialize to { foo: '' }
. Previously empty string values were discarded and foo-
would be deserialized to {foo: undefined }