Portals
Rendering children outside the parent DOM hierarchy with createPortal.
What you'll learn
- What portals are and when to use them
- Creating a portal with createPortal
- Event bubbling through portals
- Common use cases: modals, tooltips, notifications
Concept
What Are Portals?
Portals provide a first-class way to render children into a DOM node that exists outside the parent component's DOM hierarchy. Normally, a component renders its children inside its own DOM subtree. But sometimes you need to break out of that subtree — a modal dialog needs to overlay the entire page, a tooltip needs to escape a parent with overflow: hidden, or a notification needs to render at the document root. Portals let you do this while keeping the React component hierarchy intact.
Creating a Portal
You call ReactDOM.createPortal(children, container) where children is any renderable React content and container is a DOM element. The children render inside the container, which can be anywhere in the DOM — typically a dedicated div appended to document.body. Despite the visual DOM separation, the React component tree remains unchanged — the portaled component is still a child in React's tree, which means context, event bubbling, and refs all work as expected.
Event Bubbling
A key feature of portals is that events bubble through the React tree, not the DOM tree. An event fired inside a portal will bubble to parent components in the React tree, even though those parents are in a different part of the DOM. This means a onClick on a parent component will still catch clicks from a portaled child. This behavior is essential for things like closing a modal when clicking outside it — the event still propagates through the React tree correctly.
Common Use Cases
The most common use cases are modals and dialogs (which need to overlay everything and escape z-index stacking contexts), tooltips and popovers (which may need to escape overflow: hidden parents), notification toasts (rendered at the top level so they float above everything), and embedded widgets in third-party containers. For modals, also consider accessibility: trap focus inside the modal, handle Escape key, and restore focus when closed.
Example
import { useState, useEffect } from "react";
import { createPortal } from "react-dom";
function Modal({ isOpen, onClose, children }) {
useEffect(() => {
const handleEsc = (e) => { if (e.key === "Escape") onClose(); };
if (isOpen) document.addEventListener("keydown", handleEsc);
return () => document.removeEventListener("keydown", handleEsc);
}, [isOpen, onClose]);
if (!isOpen) return null;
// Render into document.body, escaping the parent's DOM hierarchy.
return createPortal(
<div className="modal-overlay" onClick={onClose}>
<div className="modal-content" onClick={e => e.stopPropagation()}>
<button className="modal-close" onClick={onClose}>×</button>
{children}
</div>
</div>,
document.body
);
}
function App() {
const [show, setShow] = useState(false);
return (
<div style={{ overflow: "hidden" }}>
<p>This div has overflow hidden, but the modal escapes it.</p>
<button onClick={() => setShow(true)}>Open Modal</button>
<Modal isOpen={show} onClose={() => setShow(false)}>
<h2>Modal Title</h2>
<p>Modal content rendered via portal.</p>
</Modal>
</div>
);
}
createPortal renders the modal into document.body, escaping the parent's overflow:hidden. Events still bubble through the React tree. Escape key closes the modal.
Try it
- Code Diff
Compare modal implementations with and without portals.
- CSS Gradient Generator
Design overlay and backdrop styles for your portal-based modals.
Common mistakes
The mistake
Creating a new portal container on every render
The fix
Create the portal container once (in a useEffect on mount or as a module-level element) and clean it up on unmount. Creating it on every render causes memory leaks and flickering.
The mistake
Forgetting to handle accessibility for modals
The fix
Modals need focus trapping, Escape key handling, aria-modal attribute, and focus restoration on close. Use a library like react-focus-lock or implement these manually for accessibility compliance.
Practice Portals
3 exercises
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.