React portals render content in a different part of the DOM without moving it out of the React tree. That makes them useful when a modal, tooltip, or similar element needs to escape an ancestor’s clipping or styling constraints—but portals do not handle positioning, event behavior, or accessibility for you.
How React portals work
createPortal(children, domNode, key?) returns a React node that renders its children inside the specified DOM node. That destination node must already exist. If it changes during an update, React recreates the portal content.
As an Amazon Associate I earn from qualifying purchases.
The key distinction is that a portal changes physical DOM placement, not React ownership. A portaled component remains part of its original React tree, so it can still read context from its React ancestors. As React puts it, “A portal only changes the physical placement of the DOM node.” React’s createPortal reference documents the API and its behavior.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →When a portal helps
Use a portal when an element needs to appear outside the visual or layout constraints of one of its DOM ancestors. For example, a modal placed inside a container styled with overflow: hidden may be clipped; rendering it elsewhere in the DOM can avoid that constraint. Tooltips and popups can face similar ancestor-style problems.
#1 Best Overall
A portal is only a placement mechanism. Your implementation still needs to determine the element’s position, stacking order, visibility, and interaction behavior. React also documents rendering into a popup DOM node supplied by a third-party widget: keep that node and render into it once it exists. See React’s portal guidance.
How portal events behave
Events from a portal bubble according to the React tree, not the physical DOM tree. Consequently, clicking inside a portal can trigger a React onClick handler on an ancestor component even when that ancestor is nowhere above the portal in the DOM.
If that behavior is unwanted, stop propagation inside the portal or move the portal higher in the React tree. When debugging an unexpected click, inspect the React ancestry as well as the DOM structure.
Recommended Free Tools
What to implement for an accessible modal
Rendering a dialog through a portal does not make it accessible. The WAI-ARIA Authoring Practices Guide modal pattern describes the interaction and semantics a modal needs. In particular, content outside the active modal should be inert: users should not be able to interact with it while the dialog is open.
- Give the dialog an accessible name. Use
aria-labelledbyreferencing a visible title, or provide anaria-label. - Move focus into the dialog on opening. For long or structurally complex content, consider initially focusing a static element near the beginning.
- Keep keyboard focus within the dialog. Tab and Shift+Tab should navigate among its controls without moving focus into inactive outside content.
- Support Escape to close when that is appropriate for the dialog, and ordinarily return focus to the element that opened it when it closes.
- Provide a visible close button in the dialog’s tab sequence.
For long or complex dialog content, the APG generally advises omitting aria-describedby when it would cause the content to be announced as one unbroken description rather than preserving its structure.
When to use aria-modal=”true”
Set aria-modal="true" only when the dialog really behaves as modal: it visually obscures the background and the application prevents interaction with outside content. The attribute does not create those behaviors. Marking a dialog modal while leaving the background interactive can mislead assistive-technology users about what they can perceive or operate.
Decide whether a portal is the right tool
Choose based on the constraint you need to solve, not on the assumption that every overlay belongs in a portal. Check whether a DOM ancestor clips or otherwise constrains the content, whether React-tree event bubbling will affect existing handlers, and what focus and keyboard behavior the overlay requires. For a modal, also confirm that the background is genuinely inert. The React and WAI-ARIA guidance does not establish portals as universally preferable; the right choice depends on the layout and interaction requirements.
Free tools Windows power users keep installed
One-click scans. No signup required.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
