Receive outside events, without leaving React's system

[philipp-spiess]

This is a feature request.

Right now, the only way to respond to "outside world" events is to leave the React's event system and add a native DOM listener. This is bad, since it will require more mental overhead when you have to work with this (you need to think about your event listener receiving a native event, or a react synthetic event). It will also simply not be possible for computed SyntheticEvents (e.g. onChange).

It also makes it very hard for react events handlers to interrupt the DOM handlers. Consider the following example, where it's not intuitive why the React listener can not stop propagation to the document. (Spoiler: React also listens on document, that's why you'd have to use SyntheticEvent#nativeEvent.stopImmediatePropagation():

var Example = React.createClass({
  render: function (){
    return (
      <div onKeyDown={function(e) { e.stopPropagation() }} />
    );
  }
});

document.addEventListener("keydown", function () {
  alert('why does this still fire?');
});

ReactDOM.render(
  <Example name="react"/>,
  document.getElementById('react')
);

An example for when you want to deal with outside events is a simple drawing tool, that must listen on keyup to stop the drawing process.

To solve this problem, I propose a new public API, something like an EventRoot. It should behave like a regular DOM Node, so that you can addEventListener() and removeEventListener(), but it's callbacks will receive the SyntheticEvent. It will get called when triggering a two phase dispatch. It respects the capture and bubble order as well as stopPropagation(). Everything you'd expect when listening on document.

For the above example, you'd only have to replace document with the new event root. The stopPropagation() can now correctly be applied.

[aweary]

Thanks for the writeup @philipp-spiess, I agree that there may be some utility in providing such an API. We've had discussion about this in the past, see #285. Would you mind posting there instead?

I'm going to close this so we don't fragment the discussion, but I encourage you to check out #285 and post your proposal there!