react-hooks-global-state

react-hooks-global-state

Simple global state for React with Hooks API

Introduction

This is a library to provide a global state with React Hooks. It has following characteristics.

• React Hooks only API without React Context
  • You don't need Context for global state.
• Hardly misusable selector by state keys
  • For most of cases, function selectors are not necessary.
• TypeScript type definitions
  • A creator function creates hooks with types inferred.
• Analogous APIs
  • useGlobalState works like React.useState.
  • useAtom resembles with the concept of Recoil.
  • createStore implies Redux.
• Concurrent Mode support
  • Under the hood, it's implemented with useMutableSource.
  • (For external stores like this, state branching is never possible.)

Install

npm install react-hooks-global-state

Usage

createAtom style

import React from 'react';
import { createAtom, useAtom } from 'react-hooks-global-state';

const initialState = { count: 0 };
const atom1 = createAtom(initialState);

const Counter = () => {
  const [count, setCount] = useAtom(atom1, 'count');
  return (
    <div>
      <span>Counter: {count}</span>
      {/* update state by passing callback function */}
      <button onClick={() => setCount(v => v + 1)}>+1</button>
      {/* update state by passing new value */}
      <button onClick={() => setCount(count - 1)}>-1</button>
    </div>
  );
};

const App = () => (
  <>
    <Counter />
    <Counter />
  </>
);

createGlobalState style

import React from 'react';
import { createGlobalState } from 'react-hooks-global-state';

const initialState = { count: 0 };
const { useGlobalState } = createGlobalState(initialState);

const Counter = () => {
  const [count, setCount] = useGlobalState('count');
  return (
    <div>
      <span>Counter: {count}</span>
      {/* update state by passing callback function */}
      <button onClick={() => setCount(v => v + 1)}>+1</button>
      {/* update state by passing new value */}
      <button onClick={() => setCount(count - 1)}>-1</button>
    </div>
  );
};

const App = () => (
  <>
    <Counter />
    <Counter />
  </>
);

createStore style

import React from 'react';
import { createStore } from 'react-hooks-global-state';

const reducer = (state, action) => {
  switch (action.type) {
    case 'increment': return { ...state, count: state.count + 1 };
    case 'decrement': return { ...state, count: state.count - 1 };
    default: return state;
  }
};
const initialState = { count: 0 };
const { dispatch, useGlobalState } = createStore(reducer, initialState);

const Counter = () => {
  const [value] = useGlobalState('count');
  return (
    <div>
      <span>Counter: {value}</span>
      <button onClick={() => dispatch({ type: 'increment' })}>+1</button>
      <button onClick={() => dispatch({ type: 'decrement' })}>-1</button>
    </div>
  );
};

const App = () => (
  <>
    <Counter />
    <Counter />
  </>
);

API

createAtom

create an atom

It returns a set of functions to be called outside React

• getStateByKey: a function to get the part of state by key outside React
• setStateByKey: a function to set the part of state by key outside React
• getState: a function to get the entire state
• setState: a function to get the entire state
• dispatch: an optional function that can be used if reducer is provided

Parameters

• initialState State
• reducer Reducer<State, Action>?

Examples

import { createAtom } from 'react-hooks-global-state';

const atom = createAtom({ count: 0 });

atom.setStateByKey('count', 1);

createGlobalState

create a gloal state

It returns a set of functions

• useGlobalState: a custom hook works like React.useState
• getGlobalState: a function to get a global state by key outside React
• setGlobalState: a function to set a global state by key outside React

Parameters

• initialState State

Examples

import { createGlobalState } from 'react-hooks-global-state';

const { useGlobalState } = createGlobalState({ count: 0 });

const Component = () => {
  const [count, setCount] = useGlobalState('count');
  ...
};

createStore

create a global store

In additon to useGlobalState which is the same hook as in createGlobalState, a store has getState and dispatch. A store works somewhat similarly to Redux, but not the same.

Parameters

• reducer Reducer<State, Action>
• initialState State (optional, default (reducer as any)(undefined,{type:undefined}))
• enhancer Enhancer<any>?

Examples

import { createStore } from 'react-hooks-global-state';

const initialState = { count: 0 };
const reducer = ...;

const store = createStore(reducer, initialState);
const { useGlobalState } = store;

const Component = () => {
  const [count, setCount] = useGlobalState('count');
  ...
};

useAtom

use atom

a custom hook that works like React.useState

Parameters

• atom Atom<State, any>
• stateKey any?

Examples

import { createAtom, useAtom } from 'react-hooks-global-state';

const atom = createAtom({ count: 0 });

const Component = () => {
  const [count, setCount] = useAtom(atom, 'count');
  ...
};

Examples

The examples folder contains working examples. You can run one of them with

PORT=8080 npm run examples:01_minimal

and open http://localhost:8080 in your web browser.

You can also try them in codesandbox.io: 01 02 03 04 05 06 07 08 09 10 11 12 13

Blogs

• TypeScript-aware React hooks for global state
• An alternative to React Redux by React Hooks API (For both JavaScript and TypeScript)
• Redux middleware compatible React Hooks library for easy global state management
• React Hooks Tutorial on pure useReducer + useContext for global state like Redux and comparison with react-hooks-global-state
• Four patterns for global state with React hooks: Context or Redux
• Steps to Develop Global State for React With Hooks Without Context

Community Wiki

• Persistence
• Optional initialState