React-portal

Struggling with modals, lightboxes or loading bars in React? Look no further. This is the component that will help you.

Features

transports its child into a new React component and appends it to the document.body
can be opened by the prop isOpened
can be opened after click on an element that you pass through the prop openByClickOn (and then it takes care of the state)
doesn't leave any DOM mess after closing
provides its child with this.props.closePortal callback
provides close on ESC and close on outside mouse click out of the box (see the docs)

Demo

Or git clone http://github.com/tajo/react-portal and open /examples/index.html

Installation

npm install react-portal --save

Usage

var React = require('react');
var Portal = require('react-portal');

var App = React.createClass({

  render: function() {
    var button1 = <button>Open portal with pseudo modal</button>;

    return (
      <Portal openByClickOn={button1} closeOnEsc={true} closeOnOutsideClick={true}>
        <PseudoModal>
          <h2>Pseudo Modal</h2>
          <p>This react component is appended to the document body.</p>
        </PseudoModal>
      </Portal>
    );
  }

});

var PseudoModal = React.createClass({

  render: function() {
    return (
      <div>
        {this.props.children}
        <p><button onClick={this.props.closePortal}>Close this</button></p>
      </div>
    );
  }

});

React.render(React.createElement(App), document.getElementById('react-body'));

Documentation - props

children : ReactElement (required)

The Portal expects one child (<Portal><Child ... /></Portal>) that will be ported.

isOpened : bool (optional)

If true, the portal is open. If false, the portal is closed. It's up to you to take care of the closing (aka taking care of the state).

openByClickOn : ReactElement (optional)

The second way how to open the portal. This element will be rendered by the portal immediately with onClick = open portal. How to close the portal then? It provides its child with the callback this.props.closePortal. Or you can use built-in portal closing (see bellow). Notice that you don't have to deal with the state (like when using the isOpened prop).

closeOnEsc: bool (optional)

If true, the portal can be closed by the key ESC.

closeOnOutsideClick: bool (optional)

If true, the portal can be closed by the outside mouse click.

onClose: func (optional)

This callback is called when the portal closes.

Tips & Tricks

Does your modal have a fullscreen overlay and the closeOnOutsideClick doesn't work? There is a simple solution.
Does your inner inner component <Portal><LevelOne><LevelTwo /></LevelOne></Portal> also need an access to this.props.closePortal()? You can't just use {this.props.children} in <LevelOne> component. You need to clone it instead: {React.cloneElement(this.props.children, {closePortal: this.props.closePortal})}.

Don't read this

Please, skip this section if you dislike dirty tricks.

States make everything harder, right? We don't want to deal with them, right? But sometime you need to open a portal (e.g. modal) automatically. There is no button to click on. No problem, because the portal has the isOpen prop, so you can just set it true or false.

However, then it's completely up to you to take care about the open state. You have to write all the closing logic! And that sucks. But there is a dirty trick:

<Portal openByClickOn={<span ref="myLittleSecret" />}>
  <Modal title="My modal">
    Modal content
  </Modal>
</Portal>

findDOMNode(this.refs.myLittleSecret).click(); // opens the portal, yay!

I'll end up in hell. I know.

Contribution

Please, create issues and pull requests.

git clone https://github.com/tajo/react-portal
cd react-portal
npm install
npm install react
gulp

Copy&paste the address from terminal to your browser. (something like http://localhost:8080)
Don't commit the main build portal.js (aka don't run npm run build)
Run gulp eslint before every commit to preserve the coding style. Do you know there is a nice real-time checking integration for your editor? ;-)

Credits

Inspired by the talk React.js Conf 2015 - Hype!, Ryan Florence

Vojtech Miksu 2015, miksu.cz, @vmiksu

aflatter / react-portal