DEV Community

fasil Zaman
fasil Zaman

Posted on

Escaping the DOM with React Portals: Practical UI Rendering Techniques

#webdev #javascript #react #frontend

Modern web apps often include dynamic elements like modals, tooltips, dropdowns, and popovers. These UI components need to float above everything else, but positioning them correctly can get tricky, especially when they're deeply nested in the DOM.

That’s where React Portals come in.

React Portals let you render components outside the normal DOM hierarchy, making it easier to handle z-index, positioning, and layering—without complicating your component logic.

In this guide, you’ll learn what React Portals are, why they matter, and how to use them to build cleaner, more flexible UIs.

🧠 What Are React Portals?

React Portals let you render a component outside its parent DOM node—perfect for things like modals or tooltips that need to break out of the usual layout, while still staying in the same React tree.

You create one using ReactDOM.createPortal.

ReactDOM.createPortal(child, container)
Enter fullscreen mode Exit fullscreen mode
  • child is the JSX you want to render.
  • container is the DOM element you want to render into.

🔥 Why Use Portals?

Here are common situations where portals solve real-world problems:

  • Modals that must appear above all content

  • Tooltips that escape overflow: hidden on parent containers

  • Dropdowns that aren't clipped or misaligned

  • Sidebars or overlays that need consistent stacking and z-index behavior

Portals bypass CSS constraints like position, z-index, and overflow by rendering outside their logical parent containers, while keeping access to props, context, and state.

🛠️ Building a Modal with React Portals

Let’s walk through creating a simple modal component using a portal.

Step 1: Add a Modal Target to index.html
In public/index.html:

<div id="root"></div>
<div id="modal-root"></div>
Enter fullscreen mode Exit fullscreen mode

The #modal-root is where the portal will mount its content.

Step 2: Create the Modal Component

// Modal.js
import React from 'react';
import ReactDOM from 'react-dom';

const Modal = ({ isOpen, onClose, children }) => {
  if (!isOpen) return null;

  return ReactDOM.createPortal(
    <div className="backdrop" onClick={onClose}>
      <div className="modal" onClick={e => e.stopPropagation()}>
        {children}
      </div>
    </div>,
    document.getElementById('modal-root')
  );
};

export default Modal;
Enter fullscreen mode Exit fullscreen mode
  • The backdrop closes the modal when clicked
  • e.stopPropagation() prevents the inner modal from closing when clicked.

Step 3: Use the Modal in Your App

// App.js
import React, { useState } from 'react';
import Modal from './Modal';

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

  return (
    <div>
      <h1>React Portals in Action</h1>
      <button onClick={() => setOpen(true)}>Open Modal</button>

      <Modal isOpen={open} onClose={() => setOpen(false)}>
        <h2>Hello from the Portal!</h2>
        <p>This modal is rendered outside the root DOM hierarchy.</p>
        <button onClick={() => setOpen(false)}>Close</button>
      </Modal>
    </div>
  );
}
Enter fullscreen mode Exit fullscreen mode

And that’s it! 🎉 You've now successfully implemented a modal using portals and integrated it into your app.

🧩 React Portals and Context

A common concern is whether components rendered through portals lose access to React context or state.

Good news: They don't. A portal maintains the React tree structure, so your modal can still use context, hooks, and any inherited state logic just like any other component.

⚠️ Tips and Common Pitfalls

  • Accessibility & Keyboard Navigation: Make sure users can navigate modals with a keyboard. Use tools like focus-trap-react to manage focus properly when a portal is open.

  • Clean Up Side Effects: If your portal sets up event listeners, timers, or intervals, be sure to clean them up when the component unmounts to avoid memory leaks.

  • Server-Side Rendering (SSR): Portals rely on the document object, which doesn’t exist during SSR. Always check that document is available before using ReactDOM.createPortal in environments like Next.js.

🧠 When Not to Use Portals

Portals are not always necessary. If your modal, tooltip, or overlay works fine inside the current DOM flow, you may not need one. Use portals when layout constraints demand rendering outside.

✅ Final Thoughts

React Portals are a handy feature that lets you control exactly where elements are rendered in the DOM, while still keeping all the benefits of React—like component structure, state management, and reactivity.

They're perfect for things like modals, dropdowns, or tooltips, letting you render content outside of the usual component hierarchy without losing the power of React. If you need precise control over where something appears, *portals are the way to go!
*

Top comments (0)