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.

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.