iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
React portals let a component render its content into a different part of the DOM without leaving its place in the React component tree. Use one when an overlay needs to escape an ancestor’s clipping or styling constraints, but remember: a portal does not position the overlay or supply modal accessibility behavior.
What a React portal changes—and what it keeps
createPortal(children, domNode, key?) renders the supplied children inside a specified DOM node. That destination node must already exist. A portal changes the content’s physical location in the DOM; it does not detach the content from its React parent. As a result, the portal’s children can still use context from React ancestors, and their events propagate through the React tree. See the React createPortal API.
If the destination DOM node changes during an update, React recreates the portal content. Choose a stable destination when you want the portaled content to remain mounted across updates.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
When a portal helps
Use a portal when the element’s normal DOM location causes an ancestor’s styles to constrain its display. For example, a modal inside a container with overflow: hidden may be clipped. Rendering the modal elsewhere in the DOM can let it escape that clipping. Tooltips and popups can face similar constraints.
#1 Best Overall
A portal is only a placement mechanism. Your implementation still needs to handle where the overlay appears, how it stacks against other content, when it is visible, and how people interact with it. React’s API also describes using a portal for content managed by a third-party widget: store the popup DOM node provided by the widget, then render into it once it exists.
How portal events reach React handlers
Events from portal children bubble according to the React tree, not the DOM tree. A click inside a portaled dialog can therefore trigger an ancestor React onClick handler even when that handler’s DOM element is not an ancestor of the dialog.
If that behavior is unwanted, stop propagation within the portal or move the portal higher in the React tree so it is not beneath the handler. Check existing ancestor handlers when adding a portal; the change in DOM placement alone does not isolate its events.
What a portal does not do for a modal
Rendering a dialog through a portal does not make it accessible or modal. You must implement the dialog’s accessible name, focus management, keyboard behavior, and handling of the content outside it. The WAI-ARIA Authoring Practices Guide modal dialog pattern says outside content should be inert while a modal dialog is active.
Give the dialog a name and a real modal state
Provide an accessible name by using aria-labelledby to reference a visible dialog title or by setting aria-label. Use aria-modal="true" only when the dialog visually obscures and actually prevents interaction with outside content. If the background remains interactive, claiming that the dialog is modal can mislead assistive technology users.
Move and contain keyboard focus
- When the dialog opens, move focus into it.
- Keep Tab and Shift+Tab navigation within the dialog while it is open.
- Include a visible close button in the dialog’s tab sequence, and support Escape to close.
- When the dialog closes, ordinarily return focus to the element that opened it.
For long or structurally complex content, consider initially focusing a static element near the beginning of the dialog. The APG generally advises omitting aria-describedby in this case if it would cause the content’s structure to be announced as one unbroken description.
Decide whether your overlay needs a portal
- Check the DOM constraints: If an ancestor clips or otherwise constrains the overlay, a portal may help. If not, rendering it in place may be simpler.
- Check React event behavior: If the overlay remains beneath a React ancestor with handlers, account for event bubbling or adjust the component structure.
- Check modal requirements: For a dialog, plan its accessible name, focus movement, keyboard support, and background inertness independently of where it renders.
Portals are not automatically preferable for every modal or tooltip. The decision depends on the constraints of the overlay’s current DOM location and the behavior your interface needs.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Quick 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.
