React Observer Mixin

A React.js Mixin with ES5 and ES6-compatible semantics which provides managed event listeners that respect component lifecycles, as well as state setters which are compatible with React invariants and are suitable for use in one-time event handlers.

This module has no runtime dependencies and weighs in at ~1.3kB minified.

Why does this exist?

Asynchronous callbacks which operate on a component's state will violate React's invariants if the component is not mounted when the callback is executed. This utility offers a mixin for React Component providing the following functionality:

• listenTo: Managed event listening respecting component lifecycles. Listeners are automatically detached when the component is un-mounted.

• setStateIfMounted: Conditional state setting which helps to avoid a violation of React's invariants when you know that you can safely drop the result of an asynchronous request.

ES6 Example

import observer from 'react-observer-mixin';

class MyComponent extends React.Component {
  constructor(props) {
    super(props);

    // Attach mixin methods and spies necessary to support them.
    observer(this);

    // The event handler automatically detaches when this component
    // is un-mounted.
    this.listenTo(props.observable, 'event', (result) => {
      this.setState({value: result});
    });

    // Other forms of async callbacks
    ajax(props.url).then((result) => {
      this.setStateIfMounted({value: result});
    });
  }
}

ES5 Example

var ObserverMixin = require('react-observer-mixin').Mixin;

var MyComponent = React.createClass({
  mixins: [ObserverMixin]
  getInitialState: function() {

    // Method documentation in the ES6 example applies here

    this.listenTo(this.props.observable, 'eventName', function(result) {
      this.setState({value: result});  
    }.bind(this));

    ajax(this.props.url1).then(function (result) {
      this.setStateIfMounted({value2: result}); 
    }.bind(this));
  }
});

Definitions

Term	Definition
Mixin	Refers to this module's Mixin object.
Observable	Object providing on or addEventListener methods. Examples include extended Event.Emitter objects and DOM nodes.

API

Module

module.Mixin

A React Mixin class which can be provided to the list of Mixins for a component.

module(React.Component)

Attach Mixin methods to a React.Component in the ES6 constructor function.

Provided Mixin Methods

this.listenTo(Observable, StringOrObject, [Function])

Attaches one or more managed listeners to an observable object. The event listeners will be automatically detached when the component is un-mounted, ensuring:

1. The user won't continue to attempt to update component state
2. VM garbage collection can clean up the component, as well as the observable once all listeners have detached.

Example:

  // ...
  getInitialState: function() {
    this.listenTo(this.props.element, 'change', function() {
      // ...
    });

    // For ease of use, multiple handlers may be attached by using
    // an object as the second parameter.
    this.listenTo(this.props.tcpClient, {
      connect: function () {
        // ...
      },
      disconnect: function () {
        // ...
      }
    });
  }

this.setStateIfMounted(Object)

Sets state if and only if the component is currently mounted. If the component is un-mounted, this call will be ignored and any given state will be silently dropped.

Contributors

Users with accepted PRs will be added to this list.

• Chris Carpita

License

MIT