Mastering React Portals: Build Complex Modals, Tooltips, and Overlays Like a Pro

React Portals allow you to render components outside the main DOM hierarchy — essential for UI elements like modals, tooltips, and dropdowns that must break out of parent boundaries. In this tutorial, you'll learn how to build a powerful modal system using portals and hooks in a clean, scalable way. Step 1: Create a Portal Target Add a dedicated in your HTML (typically inside public/index.html) for rendering portal content. Step 2: Build a Modal Component Using createPortal Use ReactDOM.createPortal to render the modal into the #modal-root. import { useEffect } from "react"; import ReactDOM from "react-dom"; function Modal({ children, onClose }) { useEffect(() => { const handleEsc = (e) => e.key === "Escape" && onClose(); window.addEventListener("keydown", handleEsc); return () => window.removeEventListener("keydown", handleEsc); }, [onClose]); return ReactDOM.createPortal( e.stopPropagation()> {children} , document.getElementById("modal-root") ); } Step 3: Use the Modal in Your App You can now drop in modals anywhere without worrying about z-index, CSS overflow, or component nesting limitations. import { useState } from "react"; function App() { const [open, setOpen] = useState(false); return ( setOpen(true)}>Open Modal {open && ( setOpen(false)}> This is a modal! Click outside or press Escape to close. )} ); } ✅ Pros Avoids z-index conflicts and CSS containment issues. Great for modals, popovers, tooltips, or context menus. Scales cleanly across apps without tight coupling. ⚠️ Cons Requires manual DOM target setup. Can complicate testing and debugging. Accessibility (e.g., focus trap) needs extra handling. Wrap-Up React Portals are a must-have pattern for any advanced frontend project. With minimal boilerplate, you can render interactive components that feel truly native to modern UIs—without breaking layout or structure. If you enjoyed this, you can support future dev-focused tutorials here: Buy Me a Coffee ☕

import { useEffect } from "react";

import ReactDOM from "react-dom";

function Modal({ children, onClose }) {

  useEffect(() => {

    const handleEsc = (e) => e.key === "Escape" && onClose();

    window.addEventListener("keydown", handleEsc);

    return () => window.removeEventListener("keydown", handleEsc);

  }, [onClose]);

return ReactDOM.createPortal(

    


      
 e.stopPropagation()>

        {children}

      


    
,

    document.getElementById("modal-root")

  );

}

import { useState } from "react";

function App() {

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

return (

    <>

       setOpen(true)}>Open Modal

      {open && (

         setOpen(false)}>

          
This is a modal!


          
Click outside or press Escape to close.

        

      )}

    

  );

}