API · React DOM
createPortal
Render outside the tree
createPortal renders a node elsewhere in the DOM while keeping it as a logical child of your component. The piece that lets modals and tooltips escape hostile overflow:hidden and z-index.
What it preserves
Even though the DOM node is elsewhere, the portal remains inside the React tree: contexts flow through it, synthetic events bubble up to the logical parent, and effects fire as if they were in place.
The destination
Usually document.body or a dedicated node with id modal-root. Make sure the destination exists before the render — mounting it in index.html is safest.
Common pitfalls
- 01The portal is visually outside the parent but logically inside: events bubble through the React tree, not the DOM tree.
- 02SSR and portals require careful handling — document.body may not exist on the server.
- 03z-index and stacking context still depend on the DOM parent — just creating a portal doesn't fix all stacking issues.
Was this helpful?
Sign in to give feedback