React Capsule 💊

React Capsule 💊 is a way to share your global React state between components without managing yet another React context.

React Capsule is simple, light-weight, easy to use, and easy to understand.

// Create a capsule by giving it an initial value.
import Capsule from 'react-capsule';
export default new Capsule('my value');

// Using capsules with function components.
import { useCapsule } from 'react-capsule';
import myCapsule from '...';

export default function MyComponent() {
  const [value, setValue] = useCapsule(myCapsule); // 💊

  // Change my capsule's value on click.
  const handleClick = React.useCallback(() => {
    setValue('your value');
  }, [setValue]);

  return <button onClick={handleClick}>{value}</button>; // my value
}

// Using capsules with class components.
import myCapsule from '...';

export default class MyComponent {
  // When the component mounts, re-render on state change.
  componentDidMount() {
    myCapsule.subscribe(this.forceUpdate);
  }

  // When the component unmounts, remove the re-render subscription.
  componentWillUnmount() {
    myCapsule.unsubscribe(this.forceUpdate);
  }

  handleClick() {
    myCapsule.setState('your value');
  }

  render() {
    // my value
    return <button onClick={this.handleClick}>{myCapsule.state}</button>;
  }
}

Install

React Capsule 💊 is available as react-capsule on NPM.

npm install react-capsule

yarn add react-capsule

API

Each capsule has a few useful methods for extending functionality or fine-tuning unit tests.

reset

capsule.reset() will reset a capsule back to its initial value. This is useful when allowing customers to reset forms, allowing customers to reset cached API results, and to run as a beforeEach in your Jest unit tests.

setState

capsule.setState(newValue) allows you to update the capsule's value. This is useful when you want to write utility functions outside a React component's render lifecycle.

state

capsule.state contains the capsule's current value.

subscribe

capsule.subscribe(callback) will execute the provided callback function whenever the state changes. This method returns a function that will unsubscribe the specified callback function.

unsubscribe

capsule.unsubscribe(callback) will unsubscribe the specified callback function from future state changes.

Sponsor 💗

If you are a fan of this project, you may become a sponsor via GitHub's Sponsors Program.