mauris / react-lh

📣 React Loud Hailer: message passing and state management for React

React Loud Hailer react-lh

Publish/subscribe implementation for efficient message passing between React components.

Install

To install react-lh with your existing React app, run either:

$ npm install --save react-lh

or if using Yarn:

$ yarn add react-lh

Usage

Recommended: Example Todo App on JSFiddle - The Todo App example demonstrates how facilitate inter-component communications and enable decoupling between them.

The following examples uses the ECMA 9 features. If you wish to use it in CommonJS module system (i.e. in Node.js natively), you need to use require() like so:

const reactlh = require('react-lh');
const loudHailer = reactlh.loudHailer;

or concisely as:

const { loudHailer } = require('react-lh');

After installing react-lh to your React app, you need to wrap components that you wish to access the Loud Hailer API with the loudHailer() function like that:

import React, { Component } from 'react';
import loudHailer from 'react-lh';

class MyComponent extends Component {
  componentDidMount() {
    const { channel } = this.props;

    channel.on('SomeOtherActionOccurred', () => {
      // a function that executes whenever the event
      // "SomeOtherActionOccurred" is fired
    });
  }

  renderButtonClickHandler() {
    return () => {
      const { channel } = this.props;

      // fires the event "ButtonClicked"
      channel.emit('ButtonClicked');
    };
  }

  render() {
    return <button onClick={this.renderButtonClickHandler()}>Press me</button>;
  }
}

// wrap the component using Loud Hailer before exporting
export default loudHailer(MyComponent);

In the case of a function component:

import React from 'react';
import loudHailer from 'react-lh';

function FuncComponent(props) {
  const { channel } = props;

  const buttonClickHandler = () => {
    channel.emit('ButtonClicked');
  };

  return <button onClick={buttonClickHandler}>Press me</button>;
}

// wrap the component using Loud Hailer before exporting
export default loudHailer(FuncComponent);

By default, the Loud Hailer API will be accessible through the channel props property. The property name can be changed by passing an option to Loud Hailer wrapper's second options argument like this:

import React from 'react';
import loudHailer from 'react-lh';

function FuncComponent(props) {
  // notice that "pipe" is used here
  const { pipe } = props;

  const buttonClickHandler = () => {
    pipe.emit('ButtonClicked');
  };

  // ...
}

const options = {
  property: 'pipe',
};
export default loudHailer(FuncComponent, options);

You can even further simplify your component as such:

import React from 'react';
import loudHailer from 'react-lh';

export default loudHailer(({ channel }) => {
  const buttonClickHandler = () => {
    channel.emit('ButtonClicked');
  };

  return <button onClick={buttonClickHandler}>Press me</button>;
});

React Hooks

With the introduction of hooks in React 16.8 or later, you can use react-lh's React Hooks:

• useChannel
• useLoudHailer
• useOnEvent
• useOnceEvent

import React, { useState } from 'react';
import { useLoudHailer } from 'react-lh';

export default (props) => {
  const [value, setValue] = useState('none');

  useLoudHailer((channel) => {
    channel.on('valueGiven', (newValue) => {
      setValue(newValue);
    });
  }, []);

  return <span>{`The value given was: ${value}`}</span>;
};

Or more concisely using useOnEvent:

import React, { useState } from 'react';
import { useOnEvent } from 'react-lh';

export default (props) => {
  const [value, setValue] = useState('none');

  useOnEvent(
    'valueGiven',
    (newValue) => {
      setValue(newValue);
    },
    []
  );

  return <span>{`The value given was: ${value}`}</span>;
};

Cross-Window Event Propagation

It is possible for events emitted by components on one window to be propagated to another window through React Loud Hailer. This is made possible by browsers' localStorage API implementation. To enable this feature, you need to wrap your top-most component (e.g. App) with the Loud Hailer CrossWindow component like this:

import React from 'react';
import ReactDOM from 'react-dom';
import { CrossWindow } from 'react-lh';

import App from './App';

const channels = ['default'];

ReactDOM.render(
  <CrossWindow channels={channels}>
    <App />
  </CrossWindow>,
  document.getElementById('root')
);

The channels property indicate which channels can be communicated across all the open windows of your website. The default channel namespace is 'default'.