redux-query-sync
Treat the URL query parameters as exposed variables of your Redux state. For example,
/mypage.html?p=14
could correspond to a state object containing {pageNumber: 14}
.
Any changes to the store state are reflected in the URL. Vice versa, if the URL is changed using the
history
module, the changed parameters are updated in the store state.
Alternatives
Similar modules exist, which you might prefer in some scenarios:
- If you already use React Router, also have a look at react-router-redux-sync. If you
prefer combining React Router with redux-query-sync, ensure you use
Router
(notBrowserRouter
) and pass to both modules the samehistory
instance (see this explanation). - If you use React without Redux, try react-url-query.
Otherwise, keep reading.
Install
npm install redux-query-sync
…or equivalent.
Usage
As a minimal example, let's say we want to synchronise query parameter dest
with the value of the
state's route.destination
field, to parse/make URLs such as directions.html?dest=Amsterdam
.
Minimal example
Note that redux-query-sync does not modify the state, but lets you specify which action to dispatch when the state should be updated. It does modify the location (using history.pushState/replaceState), but ensures to only touch the parameters you specified.
Let's look at a more elaborate example now. We sync the query parameter p
with the value of the
state's pageNumber
field, which includes a mapping between string and integer.
Longer example
Note you could equally well put the conversion to and from the string in the selector and action
creator, respectively. The defaultValue
should then of course be a string too.
See some examples in the wild:
- using string←→value conversion, using the enhancer
- have a helpful example? Send a PR to add it here
API
ReduxQuerySync()
Sets up bidirectional synchronisation between a Redux store and window location query parameters.
Param | Type | Description |
---|---|---|
options.store | Object |
The Redux store object (= an object {dispatch, getState} ). |
options.params | Object |
The query parameters in the location to keep in sync. |
options.params[].action | function: value => action |
The action creator to be invoked with the parameter value. Should return an action that sets this value in the store. |
options.params[].selector | function: state => value |
The function that gets the value given the state. |
[options.params[].defaultValue] | * |
The value corresponding to absence of the parameter. You may want this to equal the state's default/initial value. Default: undefined . |
[options.params[].valueToString] | function |
Specifies how to cast the value to a string, to be used in the URL. Defaults to javascript's automatic string conversion. |
[options.params[].stringToValue] | function |
The inverse of valueToString. Specifies how to parse the parameter's string value to your desired value type. Defaults to the identity function (i.e. you get the string as it is). |
options.initialTruth | string |
If set, indicates whose values to sync to the other, initially. Can be either 'location' or 'store' . If not set, the first of them that changes will set the other, which is not recommended. Usually you will want to use location . |
[options.replaceState] | boolean |
If truthy, update location using history.replaceState instead of history.pushState , to not add entries to the browser history. Default: false |
[options.history] | Object |
If you use the 'history' module, e.g. when using a router, pass your history object here in order to ensure all code uses the same instance. |
Returns: a function unsubscribe()
that can be called to stop the synchronisation.
ReduxQuerySync.enhancer()
For convenience, one can set up the synchronisation by passing an enhancer to createStore.
Example
const storeEnhancer = ReduxQuerySyncconst store =
Arguments to ReduxQuerySync.enhancer
are equal to those for ReduxQuerySync
itself, except that
store
can now of course be omitted. With this approach, you cannot cancel the synchronisation.