A very simple and small (1k gzipped!) state management lib for React that uses the bleeding edge React's useState hook.
Which basically means no magic behind the curtains, only pure react APIs being used to share state across components.
Try it on Codesandbox!
- Installation
- Usage
- API
- Migrating from v1.0 to v1.1
⚠️ BREAKING CHANGES: in version 1.4+,store.subscribewas simplified. check the Store Interface API
You can install the lib through NPM or grab the files in the dist folder of this repository.
npm install --save react-hookstore
This is the most basic implementation of the library. create a store with its initial state.
Later, call useStore inside components to retrieve its state and setState method.
The value passed as the first argument to the setState method will be the new state. no reducer required (but you can use a reducer, see the advanced example down below).
import React from 'react';
import { createStore, useStore } from 'react-hookstore';
createStore('clickStore', 0);
function StatefullHello() {
// just use the useStore method to grab the state and the setState methods
const [ timesClicked, setClicks ] = useStore('clickStore');
return (
<div>
<h1>Hello, component!</h1>
<h2>The button inside this component was clicked {timesClicked} times</h2>
<button type="button" onClick={() => setClicks(timesClicked+1)}>Update</button>
</div>
);
}
function AnotherComponent() {
// you can name the state whatever you want
const [ timesClicked ] = useStore('clickStore');
return (
<div>
<h1>Hello, this is a second component, with no relation to the one on the top</h1>
<h2>But it is still aware of how many times the button was clicked: {timesClicked} </h2>
</div>
)
}It is possible to create multiple stores in an app. Stores can be referenced by using their instance that is returned by the createStore method, as well as using their name.
import React from 'react';
import { createStore, useStore } from 'react-hookstore';
const clickCount = createStore('clickCountStore', 0);
createStore('nameStore', 'John Doe');
// counter will start at 2
clickCount.setState(2);
function StatefullHello() {
// this line will reference a store by its instance
const [ clicks, setClicks ] = useStore(clickCount);
// this line will reference a store by its name
const [ name ] = useStore('nameStore');
return (
<div>
<h1>Hello, {name}!</h1>
<h2>The button inside this component was clicked {clicks} times</h2>
<button type="button" onClick={() => setClicks(clicks+1)}>Update</button>
</div>
);
}Both methods can be used and mixed according to the needs, but we recomend using the instance identifiers.
We can delegate the state management to reducers (just like redux!) if we want.
import React from 'react';
import { createStore, useStore } from 'react-hookstore';
const todoListStore = createStore(
'todoList',
{
idCount: 0,
todos: [{ id: 0, text: 'buy milk' }]
},
(state, action) => {
// when a reducer is being used, you must return a new state value
switch (action.type) {
case 'add':
const id = ++state.idCount;
return {
...state,
todos: [...state.todos, { id, text: action.payload }]
};
case 'delete':
return {
...state,
todos: state.todos.filter(todo => todo.id !== action.payload)
};
default:
return state;
}
}
);
function AddTodo() {
const [state, dispatch] = useStore('todoList');
const inputRef = React.useRef(null);
const onSubmit = e => {
e.preventDefault();
const todo = inputRef.current.value;
inputRef.current.value = '';
dispatch({ type: 'add', payload: todo });
};
return (
<form onSubmit={onSubmit}>
<input ref={inputRef} />
<button>Create TODO</button>
</form>
);
}
function TodoList() {
const [{ todos }, dispatch] = useStore(todoListStore);
const deleteTodo = id => dispatch({ type: 'delete', payload: id });
return (
<ul>
<h2>TODOLIST</h2>
{todos.map(todo => (
<li key={todo.id}>
{todo.text}{' '}
<button onClick={() => deleteTodo(todo.id)} type="button">
X
</button>
</li>
))}
</ul>
);
}
export { TodoList, AddTodo };Check out the Codesandbox demo!
Creates a store to be used across the entire application. Returns a StoreInterface object.
The namespace for your store, it can be used to identify the store across the application.
The store's initial state. it can be any data type. defaults to an empty object. Optional
You can specify a reducer function to take care of state changes. the reducer functions receives two arguments, the previous state and the action that triggered the state update. the function must return a new state, if not, the new state will be null. Optional
Finds a store by its name and returns its instance.
The name of the store.
The store instance that is returned by the createStore and getStoreByName methods.
The name of the store;
A method that returns the store's current state
Sets the state of the store. works if the store does not use a reducer state handler. Otherwise, use dispatch. callback is optional and will be invoked once the state is updated, receiving the updated state as argument.
Dispatches whatever is passed into this function to the store. works if the store uses a reducer state handler. Otherwise, use setState. callback is optional and will be invoked once the state is updated, receiving the updated state as argument.
The callback function will be invoked everytime the store state changes. If the store is reducer-based, the callback function will be called with action as the first argument and state as the second. otherwise, it'll be called with state as the only argument.
the subscribe method returns a function that can be called in order to cancel the subscription for the callback function.
A function that returns a pair with the current state and a function to trigger state updates for the specified store.
The store identifier. It can be either its string name or its StoreInterface instance returned by a createStore or getStoreByName method.
- createStore now receives 3 arguments instead of an object with 3 properties.
- the name argument is now required even if only one store is being used.
// v1.0
createStore({state: 0});
createStore({
name: 'store',
state: 0,
reducer(state, action) {
return state + action;
}
})
// v1.1
createStore('myStore', 0);
createStore('store', 0, (state, value) => state + action);