React Portals let components break free from the usual parent-child DOM structure, so you can render UI in new places while keeping React’s logic and state untouched. They’re perfect for advanced features like modals, tooltips, popovers, dropdowns, and toast notifications.
What Are React Portals?
Normally, React places elements into the DOM right inside their parent component’s container. Portals use ReactDOM.createPortal to send content anywhere in the DOM—such as a dedicated modal or overlay root—without losing React's control over their props, events, and lifecycle.
Why Use Portals Instead of the Normal Tree?
- Visual overlays: Modals, dialogs, menus, and notifications that must appear above all content.
- Solving z-index & overflow issues: Popups and tooltips need to appear outside their parents’ bounds.
- Preserve React logic: Portaled children still update with React state, context, and events.
- Better accessibility: Keyboard focus and screen reader support are easier when overlays are outside scroll/clip containers.
How to Use React Portals: Step-by-Step Guide & Practical Examples
Core Steps for Using React Portals
1- Import createPortal from react-dom:
2- Create a DOM node for the portal:
Example in HTML:
3- Render your component using createPortal:
4- Use the Portal component in your React tree:
Everything inside the portal stays connected to React's component tree—state and events work as expected, but the rendered markup appears outside the parent component's DOM hierarchy
Common Use-Cases with Code Examples
Modals
Tooltips and Popovers
Dropdowns and Menus
Dropdowns sometimes render in a dedicated DOM node to avoid parent clipping.
Toast Notifications
Notification containers in portals prevent layout interference.
Accessibility Considerations
- Keyboard focus management: Move focus to a modal when opened, trap it inside, and restore on close.
- Screen reader support: Use roles like role="dialog" and aria-modal="true". Announce open state changes.
- Tab order control: Ensure tab navigation skips hidden/inactive popups.
Best Practices:
- Always close and clean up portals to avoid memory leaks.
- Manage portal state from the parent component for simplicity.
- Assign unique IDs to portal roots to avoid collisions.
- Use context for data passing if needed.
Mistakes to Avoid:
- Forgetting to handle keyboard focus or escaping.
- Nesting portals inside overflowing parents can cause invisible overlays.
- Over-complicating logic—keep portal components simple.
React Portals open up flexible, accessible UI design without losing the benefits of React’s data flow. Try them out to build advanced popups, overlays, and more!