React Portal Not Rendering— createPortal Fixed [2026]
Also covers: target DOM missing · SSR hydration mismatch · z-index stacking · event bubbling · reusable modal pattern
⚡ Common Problems
// Portal renders nothing — target element not in DOM
const portal = createPortal(<Modal />, document.getElementById("portal-root"))
// → null if #portal-root doesn't exist in HTML
// Next.js SSR error:
ReferenceError: document is not defined✅ Fix — add target to HTML and guard against SSR
<body>
{children}
<div id="portal-root" /> {/* ← target for all portals */}
</body>Why React Portals Fail to Render
React portals render to a DOM node outside your component's natural DOM position. Three things must all be true: the target DOM node must exist when the portal mounts, createPortal must run client-side (not during SSR), and the target node must not itself be constrained by CSS overflow or stacking.
Ensure the Target DOM Element Exists
Portal renders null — getElementById returns null<!-- index.html (Vite/CRA) -->
<body>
<div id="root"></div>
<div id="portal-root"></div> <!-- ← add this -->
</body>
{/* app/layout.tsx (Next.js App Router) */}
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
<div id="portal-root" /> {/* ← add after children */}
</body>
</html>
)
}
{/* Usage in a component */}
import { createPortal } from "react-dom"
function Modal({ children }: { children: React.ReactNode }) {
const el = document.getElementById("portal-root")
if (!el) return null // guard if element somehow missing
return createPortal(children, el)
}Fix SSR Hydration Mismatch with Portals
document is not defined in Next.jsReact portals use the browser DOM — they don't work during server-side rendering. Guard with a mounted state that is only set after the component mounts on the client.
"use client"
import { createPortal } from "react-dom"
import { useState, useEffect, type ReactNode } from "react"
interface PortalProps {
children: ReactNode
targetId?: string
}
export function Portal({ children, targetId = "portal-root" }: PortalProps) {
const [mounted, setMounted] = useState(false)
useEffect(() => {
setMounted(true) // only true after client-side mount
return () => setMounted(false)
}, [])
// ✅ During SSR: mounted = false → render nothing → no hydration mismatch
// After mount: render through portal
if (!mounted) return null
const target = document.getElementById(targetId)
if (!target) return null
return createPortal(children, target)
}
// Usage:
function Modal({ isOpen, onClose }: { isOpen: boolean; onClose: () => void }) {
if (!isOpen) return null
return (
<Portal>
<div className="fixed inset-0 bg-black/50 z-50 flex items-center justify-center">
<div className="bg-white rounded-xl p-6 max-w-md w-full">
<button onClick={onClose}>Close</button>
</div>
</div>
</Portal>
)
}Fix z-index and Stacking Context Issues
Portal modal hidden behind other elements/* globals.css — ensure portal-root is above everything */
#portal-root {
position: relative;
z-index: 9999; /* above all page content */
}
/* Modal overlay — fixed to viewport */
.modal-overlay {
position: fixed;
inset: 0; /* top/right/bottom/left: 0 */
background: rgba(0, 0, 0, 0.5);
z-index: 50; /* Tailwind z-50 */
display: flex;
align-items: center;
justify-content: center;
}
/* In Tailwind: */
<div className="fixed inset-0 bg-black/50 z-50 flex items-center justify-center">
<div className="relative bg-white rounded-xl shadow-2xl p-6 z-10">
{/* modal content */}
</div>
</div>The portal target at document.body level already escapes all parent overflow and stacking contexts. As long as you use position: fixed with a high z-index on the modal overlay, it will appear above all page content.
Understand Event Bubbling Through Portals
Click events propagating unexpectedlyReact portal events bubble through the React component tree (not the DOM tree). A click inside a portal bubbles to the React parent that rendered the portal. Stop propagation to prevent this when needed.
function App() {
return (
// ✅ This onClick WILL fire when clicking inside the portal modal
// because React events bubble through the React tree, not the DOM tree
<div onClick={() => console.log("App clicked!")}>
<Modal /> {/* Modal content is at document.body in DOM, but here in React tree */}
</div>
)
}
// Fix — stop propagation inside the modal if you don't want parent to fire
function Modal() {
return createPortal(
<div
className="fixed inset-0 bg-black/50 z-50"
onClick={(e) => e.stopPropagation()} // ← stop bubbling to React parent
>
<div className="modal-content" onClick={(e) => e.stopPropagation()}>
Modal content
</div>
</div>,
document.getElementById("portal-root")!
)
}Build a Reusable Modal Portal Component
Production-ready pattern with accessibility"use client"
import { createPortal } from "react-dom"
import { useEffect, useState, type ReactNode } from "react"
interface ModalProps {
isOpen: boolean
onClose: () => void
children: ReactNode
title?: string
}
export function Modal({ isOpen, onClose, children, title }: ModalProps) {
const [mounted, setMounted] = useState(false)
useEffect(() => { setMounted(true) }, [])
// Close on Escape key
useEffect(() => {
if (!isOpen) return
const handler = (e: KeyboardEvent) => {
if (e.key === "Escape") onClose()
}
document.addEventListener("keydown", handler)
return () => document.removeEventListener("keydown", handler)
}, [isOpen, onClose])
// Lock body scroll when open
useEffect(() => {
if (isOpen) document.body.style.overflow = "hidden"
return () => { document.body.style.overflow = "" }
}, [isOpen])
if (!mounted || !isOpen) return null
return createPortal(
<div
className="fixed inset-0 bg-black/50 z-50 flex items-center justify-center p-4"
onClick={onClose} // close on backdrop click
role="dialog"
aria-modal="true"
aria-label={title}
>
<div
className="bg-white rounded-2xl shadow-2xl max-w-lg w-full p-6"
onClick={e => e.stopPropagation()} // prevent backdrop close
>
{title && <h2 className="text-lg font-bold mb-4">{title}</h2>}
{children}
</div>
</div>,
document.getElementById("portal-root")!
)
}Prevention
- Add <div id="portal-root" /> to your index.html or layout.tsx before shipping any portal code
- Always guard createPortal with a mounted state in Next.js — document is not available during SSR
- Use position: fixed + high z-index on portal overlay — not position: absolute
- Stop event propagation inside portal content if you don't want clicks to bubble to React parent
- Add Escape key handler and body scroll lock to all modal portals for accessibility
- Render portal target AFTER the main app content in HTML so it naturally layers above
Frequently Asked Questions
Why is my React portal not rendering anything?+−
What is a React portal used for?+−
How do I use React portals with Next.js?+−
Does event bubbling work through React portals?+−
Why does my portal modal still get clipped by overflow: hidden?+−
Can I have multiple React portals on the same page?+−
Need Expert Help?
We Build React Components for Production
Softplix engineers build accessible, production-grade React components including modals, tooltips, and overlays. Let us help.
Talk to an Engineer