The problem

Modal dialogs are a frequently used part of web interfaces. They alert you to very important events, they allow you to confirm very dangerous actions, they can be tooltips to give you more information about something.

However, modal dialogs are very stateful. They are often presented as a reaction to something, and so this makes it hard to model in the traditional Flux model.

Dialogs are also quite tricky because they have to behave in certain ways.

Prerequisites

You should know react very well. It is helpful to know Flux, but we don't use it, and I only really discuss how that isn't enough to solve this problem.

React JS Goals

Use only react components to render modal dialogs
Keep the dialog component code as close as possible to the component that wants the dialog opened

Broader Dialog Goals

Close a dialog in response to the ESC key
Close a dialog when clicking outside of its bounds
If there are two or more dialogs, one on top of the other, close only the top dialog when responding to the keyboard or mouse

A few ways to solve this problem

There are actually a few ways to solve this problem

The first way I thought of was to have a <ModalDialog> component at the root level. For example

class Root extends React.Component {
  render() {
    return (
      <html>
        <head>
          ...
        </head>
        <body>
          <Application/>
          <ModalDialogs dialogContent={SomeStore.currentModalDialog}/>
        </body>
      </html>
    )
  }
}

We would then use something like an app dispatcher to send it a message, and it would respond

This particular approach didn't work for me for several reasons

I'm migrating a huge project to react, and there doesn't exist a root react instance
Keeping a global modal dialog instance makes it difficult to do modal dialogs on top of modal dialogs
- To do this, SomeStore.currentModalDialog would need to be an array
There would presumably be a giant switch statement somewhere and a /dialogs/ folder where I keep all my dialog component files. In this model, the dialog logic is very far from the component that wants to show that dialog, and the distance makes me uncomfortable

What I wanted

class Button extends React.Component {
  state = {
    showDialog: false
  }
  showDialog = () => {
    this.setState({
      showDialog: true
    })
  }
  hideDialog = () => {
    this.setState({
      showDialog: false
    })
  }
  render() {
    return (
      <div>
        <a onClick={this.showDialog}>This is a button</a>
        {this.state.showDialog ?
          <ModalDialog onClose={this.state.hideDialog}/>
        : null}
      </div>
    )
  }
}

In this model, I can stick <Button/> wherever I want, and it should open the dialog

How to get this to actually work... Introducing Portals!

Now that I knew what the syntax I wanted was, it was time to figure out how to actually make this work. This is when I discovered portals (or, some people call them layers, but tbh, portals sounds cooler).

Here's what a portal looks like

class Portal extends React.Component {
  _target = null // HTMLElement, a div appended to the body
  _component = null // ReactComponent, mounted on the target
  static propTypes = {
    onClose: PropTypes.func // This is called when the dialog should close
  }
  componentDidMount = () => {
    // Create a div and append it to the body
    this._target = document.body.appendChild(document.createElement('div'));

    // Mount a component on that div
    this._component = React.render(this.props.children, this._target);
  }
  componentDidUpdate = () => {
    // When the child component updates, we have to make sure the content rendered to the DOM is updated to
    this._component = React.render(this.props.children, this._target);
  }
  componentWillUnmount = () => {
    React.unmountComponentAtNode(this._target);
    document.body.removeChild(this._target);
  }
  render = () => null // Portals don't render anything themselves!
}

What this portal does, is that when it is mounted, instead of rendering to its location within, for example, <Button/>, it will create a brand new <div> as the last child in <body>, and it renders its children on that new node, effectively piping the output from <Button/> to this new div in the body: hence, "Portal".

Let's revisit the <Button> class, here's what the render function might look like now...

render() {
  return (
    <a onClick={this.showDialog}>This is a button</a>
    {this.state.showDialog ?
      <Portal>
        <div>
          This is a popup!
        </div>
      </Portal>
    : null}
  )
}