Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including constate with all npm packages installed. Try it out:

require("react/package.json"); // react is a peer dependency. var constate = require("constate")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

constate v1.1.1

Yet another React state management library that lets you work with local state and scale up to global state with ease

constate logo

Constate

NPM version NPM downloads Size Dependencies Build Status 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


import React, { useState, useContext } from "react";
import createUseContext from "constate";

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

// 2️⃣ When you need to share your state, simply wrap your hook
//    with the createUseContext factory, like so:
const useCounterContext = createUseContext(useCounter);

function Button() {
  // 3️⃣ Use container context instead of custom hook
  //    const { increment } = useCounter();
  const { increment } = useCounterContext()
  return <button onClick={increment}>+</button>;
}

function Count() {
  // 4️⃣ Use container context in other components
  //    const { count } = useCounter();
  const { count } = useCounterContext()
  return <span>{count}</span>;
}

function App() {
  // 5️⃣ Wrap your components with provider
  return (
    <useCounterContext.Provider>
      <Count />
      <Button />
    </useCounterContext.Provider>
  );
}

Installation

npm:

npm i constate

Yarn:

yarn add constate

API

createUseContext(useValue[, createMemoInputs])

Constate exports a single factory method called createUseContext. It receives two arguments: useValue and createMemoInputs (optional). And returns a wrapped hook that can now read state from the Context. The hook also has two static properties: Provider and Context.

useValue

It's any custom hook:

import { useState } from "react";
import createUseContext from "constate";

const useCounterContext = createUseContext(() => {
  const [count] = useState(0);
  return count;
});

console.log(useCounterContext); // React Hook
console.log(useCounterContext.Provider); // React Provider
console.log(useCounterContext.Context); // React Context (if needed)

You can receive arguments in the custom hook function. They will be populated with <Provider />:

const useCounterContext = createUseContext(({ initialCount = 0 }) => {
  const [count] = useState(initialCount);
  return count;
});

function App() {
  return (
    <useCounterContext.Provider initialCount={10}>
      ...
    </useCounterContext.Provider>
  );
}

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

import React, { useContext } from "react";

function Counter() {
  const count = useCounterContext();
  console.log(count); // 10
}

createMemoInputs

Optionally, you can pass in a function that receives the value returned by useValue and returns an array of inputs. When any input changes, value gets re-evaluated, triggering a re-render on all consumers (components calling useContext()).

If createMemoInputs is undefined, it'll be re-evaluated everytime Provider renders:

// re-render consumers only when value.count changes
const useCounterContext = createUseContext(useCounter, value => [value.count]);

function useCounter() {
  const [count, setCount] = useState(0);
  const increment = () => setCount(count + 1);
  return { count, increment };
}

This works similarly to the inputs parameter in React.useEffect and other React built-in hooks. In fact, Constate passes it to React.useMemo inputs internally.

You can also achieve the same behavior within the custom hook. This is an equivalent implementation:

import { useMemo } from "react";

const useCounterContext = createUseContext(() => {
  const [count, setCount] = useState(0);
  const increment = () => setCount(count + 1);
  // same as passing `value => [value.count]` to `createMemoInputs` parameter
  return useMemo(() => ({ count, increment }), [count]);
});

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:start to run examples.

License

MIT © Diego Haz

Metadata

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free