What is a React portal and when should you use one?

Normally a component's DOM output lives inside its parent's DOM node. createPortal lets React place the output somewhere else, such as document.body, while context, state and event bubbling still follow the React tree.

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

  return createPortal(
    <div className="modal-backdrop" onClick={onClose}>
      <div
        className="modal"
        role="dialog"
        aria-modal="true"
        onClick={(event) => event.stopPropagation()}
      >
        {children}
      </div>
    </div>,
    document.body,
  );
}

Why use a portal

• Escaping an ancestor with overflow: hidden
• Escaping a stacking context or transformed parent
• Placing a modal above the rest of the page
• Rendering a tooltip near the viewport edge without clipping

A portal changes the DOM location, not the logical component hierarchy. An event fired inside the portal bubbles through its React ancestors, not its DOM ancestors. That is often convenient, but it can surprise you if you expect a DOM-based outside-click handler to behave differently.