React Portals: When and How to Use Them Effectively

Introduction

React Portals provide a powerful way to render children components into DOM nodes that exist outside the parent component's hierarchy. While React's component tree naturally follows a parent-child relationship, there are cases where you need to break out of this structure—such as modals, tooltips, or notifications that should appear above other elements.

Portals allow you to render content at a different place in the DOM while maintaining React's event bubbling and context. In this post, we’ll explore when to use React Portals, how they work, and best practices for implementing them effectively.

What Are React Portals?

React Portals are a feature that lets you render a component's children into a different DOM node outside the parent hierarchy. This is particularly useful for UI elements that need to visually "escape" their container, such as dialogs, popovers, or overlays.

To create a portal, you use ReactDOM.createPortal():

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

function Modal({ children }) {
  const modalRoot = document.getElementById('modal-root');
  return ReactDOM.createPortal(children, modalRoot);
}

function App() {
  return (
    <div>
      <h1>Welcome to My App</h1>
      <Modal>
        <div className="modal">This is a modal!</div>
      </Modal>
    </div>
  );
}

Here, the Modal component renders its children into a DOM node with the ID modal-root, which could be placed anywhere in the HTML (e.g., outside the main app container).

When Should You Use React Portals?

Portals are particularly useful in the following scenarios:

1. Modals and Dialogs

Modals often need to appear above all other content, including the root app container. Without portals, z-index and CSS positioning can become messy.

2. Tooltips and Popovers

When tooltips must overflow their parent container (e.g., inside a scrollable div), portals ensure they remain visible.

3. Notifications and Toasts

Global notifications should appear outside the main app flow, often at the top or bottom of the viewport.

4. Breaking Out of Overflow: Hidden

If a parent has overflow: hidden, child elements like dropdowns may get clipped. Portals bypass this constraint.

How to Implement React Portals

Step 1: Set Up a Portal Root

First, add a DOM node outside your main app container where the portal will render:

<!DOCTYPE html>
<html>
  <head>
    <title>React Portal Example</title>
  </head>
  <body>
    <div id="root"></div>
    <div id="modal-root"></div>
  </body>
</html>

Step 2: Create a Portal Component

Define a reusable portal component:

import React, { useEffect, useRef } from 'react';
import ReactDOM from 'react-dom';

function Portal({ children }) {
  const portalRoot = document.getElementById('modal-root');
  const el = useRef(document.createElement('div'));

  useEffect(() => {
    portalRoot.appendChild(el.current);
    return () => {
      portalRoot.removeChild(el.current);
    };
  }, [portalRoot]);

  return ReactDOM.createPortal(children, el.current);
}

export default Portal;

Step 3: Use the Portal in Your App

Now, wrap any component with Portal to render it in the portal root:

function App() {
  const [showModal, setShowModal] = React.useState(false);

  return (
    <div>
      <button onClick={() => setShowModal(true)}>Open Modal</button>
      {showModal && (
        <Portal>
          <div className="modal-overlay">
            <div className="modal-content">
              <h2>Modal Title</h2>
              <button onClick={() => setShowModal(false)}>Close</button>
            </div>
          </div>
        </Portal>
      )}
    </div>
  );
}

Best Practices for Using Portals

Clean Up Portal Nodes
Always remove portal nodes when unmounting to avoid memory leaks (as shown in the useEffect cleanup).
Preserve Event Bubbling
Events triggered inside a portal still bubble up through the React component tree, not the DOM tree. This means a click inside a modal will propagate to parent React components.
Use for Specific Cases Only
Avoid overusing portals—reserve them for UI elements that truly need to break out of the parent container.
Accessibility Considerations
Ensure modals and dialogs are accessible by managing focus and adding ARIA attributes.

Conclusion

React Portals are an essential tool for rendering UI elements outside their parent hierarchy while maintaining React’s event system and context. They are particularly useful for modals, tooltips, and notifications that need to visually "escape" their container.

By following best practices—such as proper cleanup and accessibility considerations—you can leverage portals to create more flexible and maintainable UIs. Next time you encounter a scenario where an element needs to break free from its parent constraints, consider using a portal for a cleaner solution.

Would you like to see more advanced portal use cases, such as integrating with third-party libraries? Let us know in the comments!