Redux Connected UI

Purpose

Creating new state in Redux, using the standard methods - add an action type, add an action, add a reducer - can take a lot of typing. Sometimes we need local UI state in the redux store. The purpose of this library is to make keeping it there easier, and more specifically, to make connecting to the store closer to the UI that needs to be connected, easier.

Getting started

Install

npm install --save redux-connected-ui or yarn add redux-connected-ui

Note that this library expects your project to include react, react-redux and redux already.

Reducer

// store.js
import { createStore, combineReducers } from "redux";
import { connectedReducer } from "redux-connected-ui";

const rootReducer = combineReducers({
  // redux-connected-ui expects to be at the "ui" key of your store
  // if you need to use a different key, see "Using a different key" below
  ui: connectedReducer,
  ...reducers, // your other reducers
});

const store = createStore(rootReducer);

combineReducers docs

Using the Connected component

// App.js
import React from "react";
import { Provider } from "react-redux";
// note typical redux apps only have one instance of `Provider` near the top of the component tree
// Provider doesn’t need to be added anywhere else for redux-connected-ui
import store from "./store";
import { Connected } from "redux-connected-ui";

const App = () => (
  <Provider store={store}>
    <div>
      <header>
        <h1>Awesome App</h1>
      </header>
      <main>
        <Connected
          namespace="example"
          subscription="boxColor"
          initialValue="red"
        >
          {({ value, updateValue }) => (
            <div
              style={{ height: 20, width: 20, backgroundColor: value }}
              onClick={() => {
                updateValue(value === "red" ? "blue" : "red");
              }}
            />
          )}
        </Connected>
        <Connected
          namespace="example"
          subscription="myTextInput"
          initialValue="wat"
        >
          {({ value, handleInputChange }) => (
            <input value={value} onChange={handleInputChange} name="foo-42" />
          )}
        </Connected>
      </main>
    </div>
  </Provider>
);

In this example, the values from the Connected components will be in the store at state.ui.example.values.

state.ui.example.values.boxColor -> "red"
state.ui.example.values.myTextInput -> "wat"

API

Connected

Props

| Prop | Type | Required | Default | Description | | -------------------- | ------------------------------ | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | children | (renderProps) => React Element | yes | undefined | Children is a function that accepts the argument described below and returns a React element, typically would be JSX. The children function can be declared as nested JSX (as in the example above) or passed explicitly as children to Connected | | namespace | string | yes | undefined | The namespace in which to read/write the subscribed key/value | | subscription | string | yes | undefined | The key at which to read/write the subscribed value | | initialValue | any | no | undefined | The initial value for the subcribed key | | retainValueOnDestroy | boolean | no | false | Retain the current value when the rendered component unmounts. Value will be cleared by default. |

children prop render function argument

| Property | Type | Description | | ----------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | value | any | The current value of the component’s subscription | | updateValue | (newValue: any) => void | Function accepts a single argument of the new value for the component’s subscription. | | updateValues | (updateFunction: (currentValues: Object) => newValues: Object) => void | Function accepts a single argument of a function that receives the current values of the component’s namespace and must return the entire new values for the namespace | | resetValue | () => void | Function restores the component’s subscription to its initialValue when invoked | | resetValues | () => void | Function restores all values in the component’s namespace to their initialValue | | handleInputChange | (eventTarget: HtmlInputElement) => void | Value updater to be used specifically for HTML inputs. Updates the component’s subscription to event.target.value. |

ConnectAll

Props

| Prop | Type | Required | Default | Description | | --------------------- | ------------------------------ | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | children | (renderProps) => React Element | yes | undefined | Children is a function that accepts the argument described below and returns a React element, typically would be JSX. The children function can be declared as nested JSX (as in the example above) or passed explicitly as children to ConnectAll | | namespace | string | yes | undefined | The namespace to be subscribed to | | initialValues | Object | no | undefined | The initial values for the subcribed namespace. Note that this should only be used if no Connected component sets any initialValue for the same namespace. | | retainValuesOnDestroy | boolean | no | false | Retain the current values when the rendered component unmounts. Values will be cleared by default. |

children prop render function argument

| Property | Type | Description | | ------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | values | any | The current values of the component’s namespace | | updateValues | (updateFunction: (currentValues: Object) => newValues: Object) => void | Function accepts a single argument of a function that receives the current values of the component’s namespace and must return the entire new values for the namespace | | resetValues | () => void | Function restores all values in the component’s namespace to their initialValue |

Using a different key

This library exports createConnected and createConnectAll functions for connecting UI at a store key other than "ui". Usage at "otherUi" is something like this:

// MyConnectedComponents.js
import { createConnected, createConnectAll } from "redux-connected-ui";
const location = "otherUi";
export const ConnectedAtOtherUi = createConnected(location);
export const ConnectAllAtOtherUi = createConnectAll(location);

// store.js
import { createStore, combineReducers } from "redux";
import { connectedReducer } from "redux-connected-ui";

const rootReducer = combineReducers({
  // redux-connected-ui expects to be at the "ui" key of your store
  // if you need to use a different key, see "Using a different key" below
  otherUi: connectedReducer,
  ...reducers, // your other reducers
});

const store = createStore(rootReducer);