Home

Awesome

🍙 useSubstate

Lightweight (<600B minified + gzipped) React Hook to subscribe to a subset of your single app state.

function Component() {
  const [substate, dispatch] = useSubstate(state => {
    return { count: state.count };
  });

  return (
    <div>
      {substate.count}

      <button
        onClick={() => dispatch({ type: "INCREMENT" })}
      >
        Increment
      </button>
    </div>
  );
}

Features

Requirements

⚠️ To use useSubstate, you will need the unstable and experimental React 16.7.0-alpha. Check out the official documentation or this blog post by Dan Abramov for more information.

useSubstate can also be used together with react-redux in your existing Redux application. Check out Comparison To Redux for more information.

Installation

npm install --save use-substate

Usage

You can use useSubstate with your existing Redux store or with a simple alternative (like create-store). This package will export a React Context consumer (SubstateContext) as well the useSubstate hook.

This custom hook will expose an API similar to useReducer. The only argument for useSubstate is a selectSubstate function which is used to select parts of your state to be used within the component that uses the hook. This allows useSubstate to bail out if unnecessary parts change. Every component that uses this custom hook will automatically subscribe to the store.

The example below will show all steps necessary to use useSubstate:

import React, { useState } from "react";
import ReactDOM from "react-dom";

import createStore from "create-store";
import { SubstateProvider, useSubstate } from "use-substate";

const initialState = { count: 0 };
function reducer(state, action) {
  switch (action.type) {
    case "INCREMENT":
      return { count: state.count + 1 };
    case "DECREMENT":
      return { count: state.count - 1 };
  }
}
const store = createStore(reducer, initialState);

function App() {
  const [substate, dispatch] = useSubstate(state => {
    return { count: state.count };
  });

  return (
    <div>
      {substate.count}

      <button onClick={() => dispatch({ type: "INCREMENT" })}>Increment</button>
      <button onClick={() => dispatch({ type: "DECREMENT" })}>Decrement</button>
    </div>
  );
}

ReactDOM.render(
  <SubstateProvider value={store}>
    <App />
  </SubstateProvider>,
  rootElement
);

Edit useSubstate Example

Comparison To Redux

Redux is a library used to create stores that can be updated via reducers. In fact, useSubstate works flawlessly with your current Redux store.

In opposite to react-redux, this library only requires a selectSubstate function (similar to react-redux's mapStateToProps). It is meant to call the dispatch function with the action directly. Advanced concepts like connectAdvanced or mapDispatchToProps are deliberately not supported.

To use useSubstate with your current react-redux React application, find the react-redux Provider and make sure to wrap it with a SubstateProvider:

import React from "react";
import { render } from "react-dom";
import { Provider } from "react-redux";
+ import { SubstateProvider } from "use-substate";
import { createStore } from "redux";
import todoApp from "./reducers";
import App from "./components/App";

const store = createStore(todoApp);

render(
+ <SubstateProvider value={store}>
    <Provider store={store}>
      <App />
    </Provider>
+ </SubstateProvider>,
  document.getElementById("root")
);

Other Libraries

Besides the open issue in react-redux, there are two other noticeable libraries that solve the a similiar problem:

Acknowledgements

Special thanks to @sophiebits and @gaearon for helping me spot an issue in my initial implementation and showing me how to fix it.

This library is also heavily influenced by the design of useReducer, create-subscription, react-redux, Reducer components in ReasonReact, Elm, Reagent (Clojure), Om (Clojure), and a lot of other libraries that I have seen over the years. Thank you all for pushing the Web forward ❤️.

Contributing

Every help on this project is greatly appreciated. To get you started, here's a quick guide on how to make good and clean pull-requests:

  1. Create a fork of this repository, so you can work on your own environment.

  2. Install development dependencies locally:

    git clone git@github.com:<your-github-name>/use-substate.git
cd use-substate
yarn install

  3. Make changes using your favorite editor.

  4. Commit your changes (here is a wonderful guide on how to make amazing git commits).

  5. After a few seconds, a button to create a pull request should be visible inside the Pull requests section.

Future Improvements

License

MIT