React Portals – Render Components Outside the DOM Hierarchy (2025 Guide)
Introduction – What Are React Portals?
In React.js, components are rendered within the DOM tree of their parent. But what if you need to render a modal, tooltip, or dropdown that needs to appear outside this DOM hierarchy?
Enter React Portals — a powerful feature that lets you render a component into a different part of the DOM, outside the root hierarchy.
In this guide, you’ll learn:
- What React Portals are and when to use them
- How to create and render a portal
- Real-world use cases like modals and tooltips
- Best practices and accessibility tips
1. What is a React Portal?
A portal allows you to render a child component into a DOM node that exists outside the parent component’s DOM hierarchy.
Syntax:
ReactDOM.createPortal(child, container)
child: JSX to rendercontainer: DOM node to render into (outside root)
2. How to Use React Portals
Step 1: Add a DOM container to index.html
<body>
<div id="root"></div>
<div id="portal-root"></div>
</body>
Step 2: Render into the portal
import { createPortal } from 'react-dom';
function Modal({ children }) {
const portalRoot = document.getElementById('portal-root');
return createPortal(
<div className="modal">{children}</div>,
portalRoot
);
}
Usage:
function App() {
return (
<>
<h1>Main App</h1>
<Modal>
<p>This modal is rendered via Portal!</p>
</Modal>
</>
);
}
The modal appears outside the #root DOM tree
Useful for z-index management, scroll isolation, and full-screen overlays
3. Common Use Cases for Portals
| Use Case | Why Portals Help |
|---|---|
| Modals | Escape overflow: hidden of parents |
| Tooltips | Position relative to screen, not container |
| Dropdowns | Prevent clipping and overflow issues |
| Toasts/Alerts | Fixed positioning outside layout flow |
| Context menus | Independent of parent structure |
4. Styled Modal Example with Close Button
function Modal({ children, onClose }) {
return createPortal(
<div className="backdrop" onClick={onClose}>
<div className="modal" onClick={(e) => e.stopPropagation()}>
<button onClick={onClose}>Close</button>
{children}
</div>
</div>,
document.getElementById('portal-root')
);
}
Usage in App:
{isOpen && <Modal onClose={() => setIsOpen(false)}>Hello from portal!</Modal>}
Click outside to close, stop propagation inside
5. Portals & Accessibility
Add ARIA attributes for modals and dialogs:
<div role="dialog" aria-modal="true" aria-labelledby="modal-title">
<h2 id="modal-title">Modal Title</h2>
...
</div>
Trap focus with libraries like focus-trap-react
Return focus to triggering element after close
6. Portals in React DevTools
By default, portal-rendered components still appear under their parent in React DevTools, even though they exist outside in the DOM. This keeps component structure intuitive and debuggable.
Best Practices
Use portals for components that require DOM isolation
Handle escape key and outside clicks for modals
Keep your portal root (#portal-root) outside #root
Clean up any event listeners or side effects on unmount
Use context or props to pass data into portal components
Summary – Recap & Next Steps
React Portals are essential for building overlays, modals, and UI elements that need to live outside the normal DOM hierarchy. They improve flexibility without compromising component logic.
Key Takeaways:
createPortal(child, container)renders outside the DOM tree- Ideal for modals, toasts, tooltips, and dropdowns
- Maintain event bubbling and component logic
- Use with accessibility standards for keyboard and screen readers
Real-World Relevance:
Used in apps like Slack, Notion, and Stripe for popups, modals, tooltips, and notifications.
FAQ Section
What is the purpose of React Portals?
To render content into a different part of the DOM—outside the root tree—while maintaining React’s virtual DOM hierarchy.
Do Portals break event propagation?
No. Events still propagate through the React tree as if the component was rendered inside the parent.
Can I use multiple portal roots?
Yes. You can create and use multiple DOM nodes and target them as needed.
Do Portals affect styling?
Portals bypass container styles like overflow: hidden, making them ideal for modals or dropdowns that require absolute positioning.
Are React Portals supported in all browsers?
Yes. Portals are supported in all modern browsers and have been stable since React 16.
Share Now :
