Solution

You will separate a portal's logical React parentage from its physical DOM target, then make target ownership explicit.

The problem, in plain English

A tooltip may belong to a button in React but need to escape a clipping container in the DOM. React's createPortal performs that move without creating a second React root. Your component must also decide who owns the destination: it may borrow a supplied node, or create and later remove its own body-mounted host.

The mental model

Picture two maps of the same child. The React tree keeps the child under Portal, so context and synthetic events follow that relationship. The DOM tree places the child's nodes inside a separate target.

A first attempt

const { createPortal } = require('react-dom');

function Portal({ children, container }) {
  const target = container || document.body.appendChild(document.createElement('div'));
  return createPortal(children, target);
}

This creates a new host during every render, so parent updates leave empty nodes behind. It also touches document while rendering, which fails in non-browser rendering, and it never removes the node it appended. The expression hides the essential ownership distinction between a borrowed target and a host the component created.

The working solution

const React = require('react');
const { createPortal } = require('react-dom');

function Portal({ children, container = null }) {
  const [target, setTarget] = React.useState(null);

  React.useEffect(() => {
    // Effects do not run during server rendering, so DOM access stays here.
    if (typeof document === 'undefined') {
      setTarget(null);
      return undefined;
    }

    const node = container || document.createElement('div');
    const ownsNode = container === null;

    if (ownsNode) {
      node.setAttribute('data-uiready-portal', '');
      document.body.appendChild(node);
    }

    setTarget(node);

    return () => {
      // Borrowed containers outlive this component; owned hosts do not.
      if (ownsNode) node.remove();
    };
  }, [container]);

  if (target === null) return null;
  return createPortal(children, target);
}

module.exports = { Portal };

The initial null target makes the render phase independent of the browser. One effect acquires a destination and returns the matching release step. When container changes, React runs the previous cleanup before setting up the next effect, so an old owned host disappears while external containers remain untouched.

Walking through one call

Suppose <Portal><Toast /></Portal> mounts without a container.

1. The first render sees target === null, so it returns null and performs no DOM work.
2. The effect creates a div, adds the empty data-uiready-portal attribute, appends it to document.body, and stores it as the target.
3. The state update renders again. createPortal now places Toast inside that exact host.
4. A parent rerender changes the toast text. The container prop is still null, so the effect does not restart and the same host receives the updated child.
5. The caller later supplies container={sidebar}. Cleanup removes the owned host. The next effect stores sidebar without appending it, and React recreates the portal content there.
6. On unmount, React removes the portal content from sidebar, but the effect does not remove sidebar because the component never owned it.

Gotchas

• Creating a host during render — every rerender can append another node, and server rendering has no document. Fix: acquire the host in an effect.
• Removing every target — calling container.remove() on cleanup can delete DOM owned by a page shell or third-party widget. Fix: track ownership and remove only self-created hosts.
• Recreating the default host on child updates — keying the effect on children replaces the host whenever content changes. Fix: depend only on container.
• Expecting DOM bubbling rules — a click inside the target still reaches ancestors in the React tree. Fix: stop propagation in the portal child when that behavior is unwanted.
• Treating a portal as an accessible modal — moving DOM does not trap focus or add dialog semantics. Fix: build those behaviors separately when the use case is a modal.

Going further

• Accept an owned-host factory. A factory can choose an element type, attributes, or insertion point while preserving the same acquire-and-release lifecycle.
• Design an accessible modal layer. Add dialog semantics, initial focus, focus return, Escape handling, and background inertness as a separate component built on this primitive.
• Coordinate a portal registry. A registry can order toast or overlay layers, but it introduces shared state that this isolated component deliberately avoids.