Advanced React
Portals
Master React Portals, covering createPortal usage, event bubbling mechanics, DOM relocations, and overlay layouts.
1. Learning Objectives
In this lesson, you will learn how to render content outside of the standard DOM hierarchy. By the end of this topic, you will be able to:
- Differentiate standard React node rendering from Portal-based rendering.
- Mount components inside external DOM containers using
createPortal. - Explain how event bubbling works across Portal boundaries.
- Solve CSS clipping and z-index positioning issues for overlays.
- Build modular modals, tooltips, and floating menus.
2. Overview
**React Portals** provide a way to render children into a DOM node that exists outside the DOM hierarchy of the parent component. This is useful for elements like modals, tooltips, or toast notifications that need to break out of their parent containers due to CSS constraints like overflow: hidden or z-index values.
3. Why This Topic Matters
Portals solve CSS constraints when positioning layouts and elements:
- The Overflow Clipping Problem: If a parent component has `overflow: hidden` or `position: relative` set, any child component (like a modal) will be clipped or visually cut off at the parent's boundary. Portals resolve this by mounting the child directly to a top-level node like `document.body`.
- Z-Index Layering: Placing modals or tooltips deep inside the component tree often leads to z-index conflicts. Rendering them at the body level bypasses these layering issues.
4. Real-World Analogy
Think of React Portals like **a projection screen in a meeting room**:
- Standard DOM Rendering: Trying to draw a diagram directly on the room's whiteboard. If you draw past the whiteboard's frame, your drawings are cut off by the wall.
- React Portals: Using a projector (the Portal) to project your diagram onto a large screen in the center of the room. The projector controls the image from your desk (maintains component state and event handlers), but the image is displayed high on the wall, completely free of the whiteboard's boundaries.
5. Core Concepts
Below is a comparison of standard DOM rendering and React Portals:
| Property | Standard DOM Rendering | React Portals (ReactDOM.createPortal) |
|---|---|---|
| Mount Location | Nested directly inside the parent component's DOM container. | Mounted to an external DOM node (e.g., document.body). |
| CSS Constraints (overflow/z-index) | Subject to parent container clipping and z-index limitations. | Bypasses parent styles; positioned relative to the viewport. |
| Event Bubbling Flow | Bubbles up through the physical DOM tree. | Bubbles up through the virtual React component tree. |
6. Syntax & API Reference
This example shows how to write a Portal component using `createPortal`:
7. Visual Diagram
This diagram displays how Portals separate the React virtual tree from the physical DOM tree:
8. Live Example — Full Working Code
Below is a complete, single-file HTML page demonstrating a modal built with React Portals:
What just happened? Clicking "Show Modal" renders the modal inside the #modal-root element, completely outside the parent container. Because the parent container has overflow: hidden set, a standard child component would have been cut off, but the portal renders correctly. Additionally, clicking inside the modal bubbles the click event up to the parent card component, incrementing the parent's click count.
9. Interactive Playground
Try It Yourself Challenges:
- Add a call to
e.stopPropagation()inside the modal wrapper click handler, and verify that clicking the modal no longer increments the parent's click count. - Build a tooltips widget using Portals that positions itself dynamically relative to the button element.
10. Common Mistakes
| Mistake | Why it happens | Wrong | Correct |
|---|---|---|---|
| Forgetting that events bubble through portals | Even though a portal renders outside the parent DOM node, events still bubble up through the virtual React component tree. If you don't call e.stopPropagation(), click events inside the portal can trigger unexpected handlers in parent components. |
Allowing clicks inside a modal to trigger edit actions in a background card component. | Call e.stopPropagation() inside the modal content box event handler to prevent click events from bubbling up. |
| Mounting portals to missing DOM nodes during initialization | If you query for a portal container node (like document.getElementById('portal-root')) before that node has mounted in the DOM, the query returns null, causing React to throw a render error. |
createPortal(child, document.getElementById('missing')) |
Ensure the target container is declared statically in your index.html, or fallback to document.body if the node is missing. |
11. Best Practices
- Stop Event Propagation: Call `e.stopPropagation()` inside overlay content containers to prevent clicks from bubbling up to parent layout components.
- Configure static hooks targets: Declare portal mount points statically in your `index.html` file (e.g. ``) to prevent initialization errors.
- Manage accessibility: When mounting modals outside the root layout, manage keyboard focus (tab loops) and screen reader attributes (like `aria-modal="true"`) manually.
12. Browser Compatibility/Requirements
React Portals are supported in all browsers that run React.
13. Interview Questions
Q1: How does event bubbling behave in React Portals? Does it follow the physical DOM tree or the React virtual tree?
Answer: Event bubbling in React Portals follows the **React virtual tree**, not the physical DOM tree. Even though a portal component is mounted to an external DOM node (like `document.body`), events (like clicks) still bubble up through the virtual React parent hierarchy, allowing parents to catch events triggered by portal children normally.
Q2: Why do we use React Portals to render overlay widgets like modals or tooltips? What CSS constraints do they resolve?
Answer: We use portals to mount overlays outside the parent component DOM hierarchy. This resolves CSS clipping and positioning issues: (1) it prevents overlays from being clipped by parents with `overflow: hidden` or `position: relative` set, and (2) it prevents layering conflicts by rendering overlays at the body level, bypassing intermediate `z-index` limits.
14. Debugging Exercise
Identify why clicking the button inside this portal modal also triggers the parent list row selection event:
Diagnosis: Event bubbling in portals follows the virtual React tree. Because the portal is rendered inside RowItem, clicking the modal's "Close info" button bubbles the click event up to the parent div, triggering the selectRow click handler.
Fix: Add an onClick handler to the modal container that calls e.stopPropagation() to prevent events from bubbling up the virtual tree:
15. Practice Exercises
Exercise 1: Create a floating tooltips wrapper
Build a component named PortalTooltip. When hovering over an item, use a portal to mount a tooltip container to document.body. Calculate and set coordinates dynamically to align the tooltip near the trigger element.
16. Scenario-Based Challenge
The Nested Modal focus trap challenge:
You are designing a web system that uses nested modals (opening Modal B from inside Modal A). To maintain accessibility standards, you must ensure that screen readers read the active modal's content and keyboard focus is trapped within the top-level modal. Describe how you would manage this using portals and refs.
17. Quick Quiz
Q1: Which method from ReactDOM is called to mount component structures to external nodes?
A) mountOutside()
B) createPortal()
C) injectComponent()
Answer: B — createPortal() is the ReactDOM API called to render child elements into a target DOM node outside the parent tree.
18. Summary & Key Takeaways
- React Portals let you render children into DOM nodes outside the parent DOM tree.
- Portals are ideal for elements like modals, tooltips, and toast notifications.
- Events bubble up through the virtual React tree, not the physical DOM tree.
- Use
e.stopPropagation()to prevent click events from triggering unwanted parent handlers.
19. Cheat Sheet
| Portal API Element | Description |
|---|---|
createPortal(child, containerNode) |
Renders child elements inside the target DOM node. |
e.stopPropagation() |
Blocks events from bubbling up the virtual React parent hierarchy. |
document.body |
Common fallback container node target for portals. |