Portal

A component for rendering children into a different root container.

Syntax

<Portal root={container}>{children}</Portal>

Description

Portal allows you to render children into a DOM node that exists outside the parent component's DOM hierarchy. This is useful for:

When you use renderer.render(), the children are implicitly wrapped in a Portal element with the root set to the second argument.

Portal elements are opaque to their parents - they return undefined as their element value, so parent arrange operations don't see the portal's children.

Props

PropTypeDescription
rootobjectThe container to render children into
childrenChildrenThe elements to render into the root

Examples

Basic modal

import {Portal} from "@b9g/crank";

function Modal({isOpen, children}) {
  if (!isOpen) {
    return null;
  }

  return (
    <Portal root={document.body}>
      <div class="modal-overlay">
        <div class="modal-content">
          {children}
        </div>
      </div>
    </Portal>
  );
}

function App() {
  return (
    <div class="app">
      <Modal isOpen={true}>
        <h2>Modal Title</h2>
        <p>This renders at document.body level</p>
      </Modal>
    </div>
  );
}

Tooltip escaping overflow

import {Portal} from "@b9g/crank";

function* Tooltip({children, content}) {
  let isVisible = false;
  let position = {x: 0, y: 0};

  const show = (e) => {
    isVisible = true;
    position = {x: e.clientX, y: e.clientY};
    this.refresh();
  };

  const hide = () => {
    isVisible = false;
    this.refresh();
  };

  for (const {children, content} of this) {
    yield (
      <span onmouseenter={show} onmouseleave={hide}>
        {children}
        {isVisible && (
          <Portal root={document.body}>
            <div
              class="tooltip"
              style={`position: fixed; left: ${position.x}px; top: ${position.y}px;`}
            >
              {content}
            </div>
          </Portal>
        )}
      </span>
    );
  }
}

Multiple roots

import {Portal} from "@b9g/crank";

function* MultiRootApp() {
  const sidebar = document.getElementById("sidebar");
  const main = document.getElementById("main");

  for (const props of this) {
    yield (
      <>
        <Portal root={sidebar}>
          <Navigation />
        </Portal>
        <Portal root={main}>
          <Content />
        </Portal>
      </>
    );
  }
}

Event propagation

Events dispatched on elements inside a Portal still propagate through the Crank component tree, not the DOM tree:

function App() {
  const handleClick = () => console.log("Caught in App!");

  return (
    <div onclick={handleClick}>
      <Portal root={document.body}>
        {/* Click events here will still trigger handleClick */}
        <button>Click me</button>
      </Portal>
    </div>
  );
}

See also

Edit on GitHub