Create 10x Faster React Apps Using AI
Topics
What is a React Portal?
Why use createPortal React?
What is the difference between React createRoot and createPortal?
How do you create a portal in ReactJS?
Why use portals for UI overlays? This blog explains how React portals solve common layout issues by letting you render elements elsewhere in the DOM. Learn when and how to use portals effectively to build reliable, well-behaved overlays in your projects.
UI overlays like modals, tooltips, and dropdown menus often face a tricky challenge: they need to appear outside their original spot in the component tree to avoid being hidden or clipped. This is where the concept of portals comes into play.
But why would you want to render a UI element somewhere else entirely?
If you’re working on a create portal React project, understanding how to manage these overlays properly can save you from frustrating layout issues.
This blog will walk you through how portals function, when to apply them, and the small details that make a big difference in real-world applications. By the end, you’ll be able to create overlays that behave reliably and look great.
A React portal is a method for rendering UI elements into a different DOM node from where the React component logically lives in the React tree. This means a child component can be created in the component hierarchy but end up being attached somewhere else in the DOM hierarchy, such as directly inside the document body.
You still keep the parent-child relationship in terms of data flow and event handling. The difference is only in the placement in the DOM tree. This gives you the flexibility to bypass structural and styling limitations that come from the parent component.
Portals are often used when rendering elements like modal dialogs that must overlay the entire application. Without portals, a modal might be constrained by CSS overflow or z-index values from a parent component.
Common reasons include:
These cases are where portals can bypass styling and layout restrictions while keeping your React application logic intact.
When using a portal, the visual elements are rendered in a different location in the DOM tree. Even though they are mounted into a separate dom node, the events emitted by those elements still bubble up through the React tree as if they were placed inside the original parent component.
This is what makes portals both practical and intuitive. You can still manage state and event handlers as you would for any other component while having the content displayed elsewhere.
The portal component stays in the same React tree as the parent component. Its portal content, however, is mounted into a different DOM node in the DOM hierarchy.
Here is the following code example using import createPortal from react and createPortal from react-dom:
1// App.js 2import React from 'react'; 3import ReactDOM from 'react-dom'; 4import './styles.css'; 5 6function Modal({ children }) { 7 return ReactDOM.createPortal( 8 <div className="modal">{children}</div>, 9 document.getElementById('modal-root') // root dom element for portal 10 ); 11} 12 13export default function App() { 14 return ( 15 <div> 16 <h1>Main App Content</h1> 17 <Modal> 18 <p>This is rendered outside the parent component’s DOM hierarchy</p> 19 </Modal> 20 </div> 21 ); 22} 23
Explanation:
| Use Case | Why a Portal Helps | Example |
|---|---|---|
| Modal dialogs | Avoid clipping and z-index issues | Login form overlay |
| Tooltip components | Escape scrollable parent div constraints | Hover tooltips |
| Dropdown menus | Align over other UI without layout issues | User menu |
| Toast notifications | Show over entire application UI | Alerts |
This structure allows you to reliably render components in a different DOM node regardless of how deep they are in the component hierarchy.
When styling portals in a React application, pay attention to how they interact with the rest of the UI. Positioning with fixed or absolute values often works best for overlays. You must also consider screen readers and assistive technologies.
Things to focus on:
For modal component overlays, adding ARIA labels and focus management helps guide users. Without such handling, the portal content may confuse screen readers.
Looking to build powerful React apps without writing code? Rocket.new lets you create any app with simple prompts—no code required. Start building your next React project today with ease and speed!
Even though portals place elements in a different location in the DOM hierarchy, event bubbling follows the React tree. This means that clicking a button inside a modal content can still trigger event handlers in the parent component.
This behavior lets you keep your render components' logic unchanged while still placing UI elements in a different DOM node.
Multiple Portals in One Application
You can have several portal component instances for modal dialogs, tooltips, and notifications.
Using the Portal’s Key for Rendering
Assigning a unique string as the portal's key can help control rendering and avoid unnecessary re-rendering when switching between overlays.
Cleanup on Component Unmount
Always handle component unmount properly to prevent memory leaks, especially when dealing with timers or animations inside portal content.
1import React, { useState } from 'react'; 2import ReactDOM from 'react-dom'; 3 4function Modal({ onClose, children }) { 5 return ReactDOM.createPortal( 6 <div className="modal" onClick={onClose}> 7 {children} 8 </div>, 9 document.getElementById('modal-root') 10 ); 11} 12 13export default function App() { 14 const [open, setOpen] = useState(false); 15 16 return ( 17 <div> 18 <button onClick={() => setOpen(true)}>Open Modal</button> 19 {open && ( 20 <Modal onClose={() => setOpen(false)}> 21 <h2>Modal Title</h2> 22 <input type="text" placeholder="Enter something" /> 23 {/* user input */} 24 </Modal> 25 )} 26 </div> 27 ); 28}
Explanation:
When working with React portals, some common problems can arise. Here’s what to watch out for:
Z-index conflicts:
Check the DOM hierarchy and ensure your portal is attached to the correct DOM element to avoid overlays being hidden behind other elements.
Memory leaks:
Always clean up timers, event listeners, or subscriptions inside portal content on component unmount to prevent memory leaks.
Unexpected behavior in event propagation:
Remember that events emitted inside a portal still bubble through the React tree, even though the portal content is rendered in a different DOM node. This can affect event handlers in the parent component.
Incorrect portal target:
Verify that the root DOM element for your portal exists in the HTML file and matches the element you are rendering into.
Styling issues:
Position overlays with fixed or absolute CSS styles to avoid clipping or unwanted scroll effects caused by the parent div’s DOM hierarchy.
To get the most out of React portals and avoid common pitfalls, consider the following guidelines:
Keep portal content focused:
Limit the portal component to only the UI overlay or content that needs to be rendered outside the parent component's DOM hierarchy. Avoid putting large or complex components unnecessarily inside portals.
Avoid deeply nested portals:
Building multiple levels of portals in the component hierarchy can complicate the DOM tree and make event propagation and styling harder to manage.
Use dedicated root DOM elements for portals:
Always create specific root elements (like a div with an ID such as modal-root or tooltip-root) in your HTML file to serve as targets for your portals. This improves clarity in the DOM hierarchy and styling control.
Manage component unmount carefully:
Clean up any timers, subscriptions, or event handlers inside portal content during component unmount to prevent memory leaks.
Test accessibility thoroughly:
Add ARIA roles and attributes to portal overlays, especially modal dialogs. Use keyboard focus management to trap focus inside overlays and assistive technologies like screen readers.
Inspect portal placement with developer tools:
Use browser dev tools to verify that your portal content is rendered in the intended DOM node, not accidentally inside the parent component’s DOM hierarchy.
Use unique keys for multiple portals:
When rendering several portal components dynamically, assign an optional key to each portal to avoid unnecessary re-renders and maintain React's reconciliation efficiency.
Handle event propagation deliberately:
Keep in mind that even though the portal content is rendered in a different DOM node, events bubble through the React tree. Structure event handlers accordingly to avoid unexpected side effects.
When working on overlays in modern interfaces, the create portal React pattern allows you to build components that are maintainable, accessible, and properly styled. By controlling where your UI is rendered in the DOM hierarchy without breaking the component hierarchy, you gain flexibility and control. Starting with a basic modal component is a good first step in applying portals in your React application.
