react-portal

What is react-portal?

The react-portal package allows you to render components into a DOM node that exists outside the DOM hierarchy of the parent component. This is useful for creating modals, tooltips, and other UI elements that need to be rendered outside the main document flow.

What are react-portal's main functionalities?

Basic Portal Usage

This example demonstrates the basic usage of the react-portal package. It renders a div element outside the main DOM hierarchy, which can be useful for creating modals or tooltips.

import React from 'react';
import ReactDOM from 'react-dom';
import { Portal } from 'react-portal';

function App() {
  return (
    <div>
      <h1>Main App</h1>
      <Portal>
        <div style={{ position: 'absolute', top: '50px', left: '50px', background: 'white', border: '1px solid black', padding: '10px' }}>
          This is a portal content
        </div>
      </Portal>
    </div>
  );
}

export default App;

Custom Portal Target

This example shows how to use a custom DOM node as the target for the portal. The content will be rendered inside the specified custom target element.

import React, { useRef } from 'react';
import ReactDOM from 'react-dom';
import { Portal } from 'react-portal';

function App() {
  const customTarget = useRef(null);

  return (
    <div>
      <h1>Main App</h1>
      <div ref={customTarget} id="custom-target" style={{ position: 'relative', height: '200px', border: '1px solid black' }}>
        Custom Target
      </div>
      <Portal node={customTarget.current}>
        <div style={{ position: 'absolute', top: '10px', left: '10px', background: 'white', border: '1px solid black', padding: '10px' }}>
          This is a portal content inside custom target
        </div>
      </Portal>
    </div>
  );
}

export default App;

Other packages similar to react-portal

react-dom

The react-dom package provides the createPortal function, which allows you to render children into a DOM node that exists outside the DOM hierarchy of the parent component. It is a part of the React core library and offers similar functionality to react-portal.

react-reverse-portal

The react-reverse-portal package allows you to create portals that can be moved around in the DOM. It provides more advanced features compared to react-portal, such as the ability to move portals between different parts of the DOM dynamically.

react-teleport

The react-teleport package offers a simple API for rendering components outside the main DOM hierarchy. It is similar to react-portal but provides additional features like teleporting components to different parts of the DOM based on conditions.

README

React-portal

Struggling with modals, lightboxes or loading bars in React? Look no further. React-portal creates a new top-level React tree and injects its child into it.

Features

• transports its child into a new React component and appends it to the document.body (creates a new independent React tree)
• can be opened by the prop isOpened
• can be opened after a click on an element that you pass through the prop openByClickOn (and then it takes care of the open/close state)
• doesn't leave any mess in DOM after closing
• provides its child with this.props.closePortal callback
• provides close on ESC and close on outside mouse click out of the box
• supports absolute positioned components (great for tooltips)

Demo

Try http://miksu.cz/react-portal or

git clone https://github.com/tajo/react-portal

and open

/examples/index.html

Installation

npm install react react-dom react-portal --save

Usage

import React from 'react';
import ReactDOM from 'react-dom';
import Portal from 'react-portal';

export default class App extends React.Component {

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

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

}

export class PseudoModal extends React.Component {

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

}

ReactDOM.render(<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). Don't use this prop if you want to make your life easier. Use openByClickOn instead!

openByClickOn : ReactElement (optional)

The second way how to open the portal. This element will be rendered by the portal immediately with onClick handler that triggers portal opening. How to close the portal then? The portal provides its ported child with a callback this.props.closePortal. Or you can use built-in portal closing methods (closeOnEsc, ... more below). Notice that you don't have to deal with the open/close 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 <LevelTwo />

<Portal>
  <LevelOne>
    <LevelTwo />
  </LevelOne>
</Portal>

also needs an access to this.props.closePortal()? You can't just use {this.props.children} in render method of <LevelOne> component. You have 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>

ReactDOM.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 react-dom
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