React Portals

React Portals provide a way to render children into a different part of the DOM — outside of the parent component’s hierarchy — without breaking React’s data flow or event handling. You can think of a Portal as a “teleport” for React elements — it allows a component to visually appear somewhere else in the DOM, but logically remain connected to its parent component.

Why Use Portals?

Portals are most useful when you need to render UI elements that must appear above other elements or outside normal layout flow, such as:

Modals / Dialogs
Tooltips and Popovers
Dropdown Menus
Notifications or Toast messages
Context Menus

For example, a modal should appear above all content and not be affected by CSS overflow or z-index limitations of its parent container.

How Portals Work

Normally, React components render inside the DOM node defined by your app’s root (e.g., #root).

With portals, you can render components inside another DOM node, such as #modal-root.

Syntax

ReactDOM.createPortal(child, container)

child → The React element to render.
container → The DOM node where the element should be mounted.

Example: Rendering a Modal using a Portal

Step 1: Create a modal root in index.html

<body>
  <div id="root"></div>
  <div id="modal-root"></div> <!-- Portal target -->
</body>

Step 2: Create a Modal component

import React from "react";
import ReactDOM from "react-dom";

function Modal({ children }) {
  const modalRoot = document.getElementById("modal-root");
  return ReactDOM.createPortal(
    <div className="modal-overlay">
      <div className="modal-content">{children}</div>
    </div>,
    modalRoot
  );
}

export default Modal;

Step 3: Use the Modal component

import React, { useState } from "react";
import Modal from "./Modal";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <div>
      <h1>React Portal Example</h1>
      <button onClick={() => setOpen(true)}>Open Modal</button>

      {open && (
        <Modal>
          <h2>Hello from the Portal!</h2>
          <button onClick={() => setOpen(false)}>Close</button>
        </Modal>
      )}
    </div>
  );
}

export default App;

The modal is rendered outside the root DOM (in #modal-root).
React’s event bubbling still works — clicking the “Close” button updates the open state in App.
The component behaves as part of the React tree even though it’s outside the normal DOM hierarchy.

Event Propagation in Portals

One of the best things about Portals is that events still propagate normally through the React tree. That means even if your modal is rendered outside the root DOM, event handlers in parent components will still work as expected.

Real-World Use Cases

Modal dialogs — Appear on top of everything.
Tooltips & Popovers — Avoid clipping or overflow issues.
Dropdown menus — Display over other elements without layout problems.
Toast notifications — Display temporary messages globally.

Advantages of React Portals

Clean separation between structure and presentation
No CSS conflicts with parent containers
Fully React-controlled (no manual DOM manipulation)
Event propagation remains intact
Great for accessibility and layering

Summary Table

Feature	Description
Purpose	Render React elements outside the root DOM node
Method	`ReactDOM.createPortal(child, container)`
Common Uses	Modals, tooltips, dropdowns, popups
Benefits	Avoids layout issues, keeps React tree intact, supports event bubbling

React Handbook