Constate

React Context + State

State managementReact
diegohaz/constateconstate

README

constate logo


Constate


NPM versionNPM downloadsSizeDependenciesGitHub Workflow Status (branch)Coverage Status

Write local state using React Hooks and lift it up to React Context only when needed with minimum effort.

🕹 CodeSandbox demos 🕹
Counter I18n Theming TypeScript Wizard Form

Basic example


  1. ``` js
  2. import React, { useState } from "react";
  3. import constate from "constate";

  5. // 1️⃣ Create a custom hook as usual
  6. function useCounter() {
  7.   const [count, setCount] = useState(0);
  8.   const increment = () => setCount(prevCount => prevCount + 1);
  9.   return { count, increment };
  10. }

  12. // 2️⃣ Wrap your hook with the constate factory
  13. const [CounterProvider, useCounterContext] = constate(useCounter);

  15. function Button() {
  16.   // 3️⃣ Use context instead of custom hook
  17.   const { increment } = useCounterContext();
  18.   return <button onClick={increment}>+</button>;
  19. }

  21. function Count() {
  22.   // 4️⃣ Use context in other components
  23.   const { count } = useCounterContext();
  24.   return <span>{count}</span>;
  25. }

  27. function App() {
  28.   // 5️⃣ Wrap your components with Provider
  29.   return (
  30.     <CounterProvider>
  31.       <Count />
  32.       <Button />
  33.     </CounterProvider>
  34.   );
  35. }
  36. ```

Learn more

Advanced example


  1. ``` js
  2. import React, { useState, useCallback } from "react";
  3. import constate from "constate";

  5. // 1️⃣ Create a custom hook that receives props
  6. function useCounter({ initialCount = 0 }) {
  7.   const [count, setCount] = useState(initialCount);
  8.   // 2️⃣ Wrap your updaters with useCallback or use dispatch from useReducer
  9.   const increment = useCallback(() => setCount(prev => prev + 1), []);
  10.   return { count, increment };
  11. }

  13. // 3️⃣ Wrap your hook with the constate factory splitting the values
  14. const [CounterProvider, useCount, useIncrement] = constate(
  15.   useCounter,
  16.   value => value.count, // becomes useCount
  17.   value => value.increment // becomes useIncrement
  18. );

  20. function Button() {
  21.   // 4️⃣ Use the updater context that will never trigger a re-render
  22.   const increment = useIncrement();
  23.   return <button onClick={increment}>+</button>;
  24. }

  26. function Count() {
  27.   // 5️⃣ Use the state context in other components
  28.   const count = useCount();
  29.   return <span>{count}</span>;
  30. }

  32. function App() {
  33.   // 6️⃣ Wrap your components with Provider passing props to your hook
  34.   return (
  35.     <CounterProvider initialCount={10}>
  36.       <Count />
  37.       <Button />
  38.     </CounterProvider>
  39.   );
  40. }
  41. ```

Learn more

Installation


npm:

  1. ```sh
  2. npm i constate
  3. ```

Yarn:

  1. ```sh
  2. yarn add constate
  3. ```

API


constate(useValue[, ...selectors])


Constate exports a single factory method. As parameters, it receives [useValue](#usevalue) and optional [selector](#selectors) functions. It returns a tuple of [Provider, ...hooks].

useValue


It's any custom hook:

  1. ``` js
  2. import { useState } from "react";
  3. import constate from "constate";

  5. const [CountProvider, useCountContext] = constate(() => {
  6.   const [count] = useState(0);
  7.   return count;
  8. });
  9. ```

You can receive props in the custom hook function. They will be populated with ``:

  1. ``` js
  2. const [CountProvider, useCountContext] = constate(({ initialCount = 0 }) => {
  3.   const [count] = useState(initialCount);
  4.   return count;
  5. });

  7. function App() {
  8.   return (
  9.     <CountProvider initialCount={10}>
  10.       ...
  11.     </CountProvider>
  12.   );
  13. }
  14. ```

The API of the containerized hook returns the same value(s) as the original, as long as it is a descendant of the Provider:

  1. ``` js
  2. function Count() {
  3.   const count = useCountContext();
  4.   console.log(count); // 10
  5. }
  6. ```

selectors


Optionally, you can pass in one or more functions to split the custom hook value into multiple React Contexts. This is useful so you can avoid unnecessary re-renders on components that only depend on a part of the state.

A selector function receives the value returned by [useValue](#usevalue) and returns the value that will be held by that particular Context.

  1. ``` js
  2. import React, { useState, useCallback } from "react";
  3. import constate from "constate";

  5. function useCounter() {
  6.   const [count, setCount] = useState(0);
  7.   // increment's reference identity will never change
  8.   const increment = useCallback(() => setCount(prev => prev + 1), []);
  9.   return { count, increment };
  10. }

  12. const [Provider, useCount, useIncrement] = constate(
  13.   useCounter,
  14.   value => value.count, // becomes useCount
  15.   value => value.increment // becomes useIncrement
  16. );

  18. function Button() {
  19.   // since increment never changes, this will never trigger a re-render
  20.   const increment = useIncrement();
  21.   return <button onClick={increment}>+</button>;
  22. }

  24. function Count() {
  25.   const count = useCount();
  26.   return <span>{count}</span>;
  27. }
  28. ```

Contributing


If you find a bug, please create an issue providing instructions to reproduce it. It's always very appreciable if you find the time to fix it. In this case, please submit a PR.

If you're a beginner, it'll be a pleasure to help you contribute. You can start by reading the beginner's guide to contributing to a GitHub project.

When working on this codebase, please use yarn. Run yarn examples to run examples.

License


MIT © Diego Haz