Understanding React Portals: A Powerful Tool for DOM Manipulation

React Portals are an advanced feature in React that allows developers to render children into a DOM node that exists outside the hierarchy of the parent component. Introduced in React 16, portals provide a first-class way to manage parts of the UI that need to break out of the typical component tree.

In this article, we’ll explore what React Portals are, when and why to use them, and how to implement them in a real-world application.

What is a React Portal?

In a typical React application, components are rendered inside a root DOM node, often called #root. This means the entire component tree is nested under this one node. However, there are cases where we need to render a component outside this root hierarchy. This is where React Portals come in.

Definition:

A React Portal provides a way to render children into a DOM node that exists outside the DOM hierarchy of the parent component.

Syntax

React provides a method called ReactDOM.createPortal for creating a portal.

ReactDOM.createPortal(child, container)

• **child**: The React element you want to render.
• **container**: The DOM node where the child will be mounted.

Example:

import React from 'react';
import ReactDOM from 'react-dom';
const Modal = ({ children }) => {
  return ReactDOM.createPortal(
    <div className="modal">
      {children}
    </div>,
    document.getElementById('modal-root') // This is outside the root div
  );
};

Here, the Modal component renders its children into a DOM node with the ID modal-root, which is outside the root component's DOM tree.

When to Use React Portals

React Portals are ideal for UI components that need to visually and functionally break out of their parent hierarchy. Common use cases include:

• Modals/Dialogs: To prevent z-index or overflow issues.
• Tooltips and Popovers: To ensure they position correctly relative to the viewport.
• Dropdown Menus: When the dropdown should render outside scrollable containers.

Setting Up a Portal

Here’s how you can set up a basic portal:

Step 1: Create a Portal Component

// Modal.js
import React from 'react';
import ReactDOM from 'react-dom';
const Modal = ({ isOpen, onClose, children }) => {
  if (!isOpen) return null;
  return ReactDOM.createPortal(   //Use this to create portal
    <div className="modal-overlay">
      <div className="modal-content">
        <button onClick={onClose}>Close</button>
        {children}
      </div>
    </div>,
    document.getElementById('body') //render on to document body
  );
};
export default Modal;

Step 2 : Use the Portal in Your App

// App.js
import React, { useState } from 'react';
import Modal from './Modal';
function App() {
  const [isModalOpen, setIsModalOpen] = useState(false);
  return (
    <>
      <button onClick={() => setIsModalOpen(true)}>Open Modal</button>
      <Modal isOpen={isModalOpen} onClose={() => setIsModalOpen(false)}>
        <h2>Hello from the Modal!</h2>
      </Modal>
    </>
  );
}
export default App;

In Summary: React Portals Solve These Key Problems

1. Z-index conflicts — Renders outside stacking context of parent
2. Overflow/scroll clipping — Avoids being trapped inside scrollable or hidden containers.
3. Incorrect positioning — Positions relative to the viewport or body

But wait, though they solve these challenges, they introduce new set of challenges,

1. Context mismatch — In your application if you are using <Provider> they may not get passed properly to the portal components
2. Event Bubbling may not work properly.
3. CSS Variables may not get passed properly, as it breaks out of normal document flow the CSS variable might not get passed properly.

Solution : Try to specify the container in the createPortal near to the DOM element(closest DOM) where you want to render the element.

Conclusion

React Portals are an essential tool for developers who want to build flexible and accessible UIs. Whether you’re dealing with modals, tooltips, or any UI element that needs to escape its parent DOM tree, portals offer a clean and reliable solution, but they introduce another set of problem, so use cautiously.