Build UI Overlays with Create Portal: What You Need to Know

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.

What are Portals in React?

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.

Why Use Portals?

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:

• Displaying modal dialogs over the entire application without being clipped.
• Showing tooltip components that escape overflow restrictions of a parent div.
• Positioning dropdown menus above other UI elements regardless of their location in the component hierarchy.
• Rendering toast notifications outside the root element so they stay visible at all times.

These cases are where portals can bypass styling and layout restrictions while keeping your React application logic intact.

How Portals Work in the DOM?

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.

Creating a Basic Portal

Here is the following code example using import createPortal from react and createPortal from react-dom:

Copy
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:

• The modal component uses the createPortal function from React DOM.
• Even though it is called inside the app component, the resulting HTML is placed in a separate root element (#modal-root), not the root div element of the main React application.

Portal Use Cases in a Real React Application

This structure allows you to reliably render components in a different DOM node regardless of how deep they are in the component hierarchy.

Styling and Accessibility with Portals

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:

• Use CSS position rules like fixed or absolute for reliable overlay placement.
• Make sure portal content visually aligns with related elements, even if in a different DOM node.
• Add ARIA attributes to modal component overlays to guide screen readers.
• Implement focus trapping inside modal dialogs so keyboard navigation stays within the overlay.
• Test the portal component with assistive technologies to confirm accessibility compliance.

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!

Start Building Now!

Event Bubbling and Portals

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.

Advanced Patterns with React Portals

1. Multiple Portals in One Application

   You can have several portal component instances for modal dialogs, tooltips, and notifications.

2. 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.

3. Cleanup on Component Unmount

   Always handle component unmount properly to prevent memory leaks, especially when dealing with timers or animations inside portal content.

Example with State and User Input in Portals

Copy
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:

• The modal component is placed outside the parent component's DOM hierarchy.
• User input inside the portal still updates the state of the app component as expected.

Troubleshooting Common Issues

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.

Best Practices for Using Portals

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.

Making the Most of Create Portal in React

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.