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 (not BrowserRouter) and pass to both modules the same history 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

import ReduxQuerySync from 'redux-query-sync'

ReduxQuerySync({
    store, // your Redux store
    params: {
        dest: {
            // The selector you use to get the destination string from the state object.
            selector: state => state.route.destination,
            // The action creator you use for setting a new destination.
            action: value => ({type: 'setDestination', payload: value}),
        },
    },
    // Initially set the store's state to the current location.
    initialTruth: 'location',
})

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

import ReduxQuerySync from 'redux-query-sync'

ReduxQuerySync({
    store,
    params: {
        p: {
            selector: state => state.pageNumber,
            action: value => ({type: 'setPageNumber', payload: value}),

            // Cast the parameter value to a number (we map invalid values to 1, which will then
            // hide the parameter).
            stringToValue: string => Number.parseInt(string) || 1,

            // We then also specify the inverse function (this example one is the default)
            valueToString: value => `${value}`,

            // When state.pageNumber equals 1, the parameter p is hidden (and vice versa).
            defaultValue: 1,
        },
    },
    initialTruth: 'location',

    // Use replaceState so the browser's back/forward button will skip over these page changes.
    replaceState: true,
})

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 = ReduxQuerySync.enhancer({
    params,
    initialTruth,
    replaceState,
})
const store = createStore(reducer, initialState, storeEnhancer)

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.