DOM & EventsSuperseded

React Portals and z-index Layering (Legacy Pattern)

Mental Model

createPortal(..., document.body) escaped local CSS Stacking Context traps by teleporting DOM nodes to <body>. With the Browser Top Layer now universal, Native Dialog and Popover API supersede manual portals.

Interactive Simulator

createPortal + z-index Hack vs Native Top Layer

Lines of Code
Before
6
After
4
Reflows / Browser Cost
Before
DOM reparent + z-index wars
After
Native Top Layer
BeforeLegacy Portal + Manual Focus/z-index
createPortal(
  <div className="fixed inset-0 z-[9999]">
    <FocusTrap><Modal /></FocusTrap>
  </div>,
  document.body
);
Lines: 6Reflows: DOM reparent + z-index warsDependencies: FocusTrap + ScrollLock libs

Requires manual Escape key, focus trap, inert siblings, and z-index coordination.

After (Native)Native <dialog>.showModal() / [popover]
<dialog ref={ref} onCancel={onClose}>
  <ModalContent />
</dialog>
// ref.current.showModal() promotes to Top Layer
Lines: 4Reflows: Native Top LayerDependencies: 0 JS overlay libs

Automatic Top Layer, ::backdrop, Escape dismiss, and background inertness.

Under the Hood

Picture mailing your furniture to a neighbor's rooftop just so it sits higher than your ceiling: createPortal relocates the DOM node to document.body, yet still leaves you wiring Escape keys, focus traps, and z-index treaties with every other tenant.

  1. DOM Reparenting: createPortal keeps React's synthetic event bubbling intact while mounting the real DOM subtree under document.body.
  2. Global z-index Collisions: Portals still compete inside the root stacking context (z-50 vs z-[9999]).
  3. Manual A11y: Without <dialog>.showModal(), JS must trap Tab focus, lock body scroll, and restore focus on close.
JSX
// Superseded: portal + hardcoded z-index
createPortal(<div className="fixed inset-0 z-[9999]">{children}</div>, document.body);

// Modern replacement: stays inline in component DOM, renders in Top Layer
<dialog ref={dialogRef} className="backdrop:bg-black/50">{children}</dialog>

Problem Genealogy

  • 2017 (ReactDOM.createPortal): Solved overflow: hidden clipping in nested component trees.
  • 2018–2023 (Overlay Library Stack): Spawned react-focus-lock, body-scroll-lock, and Floating UI z-index managers.
  • 2024 (Top Layer Baseline): <dialog> and [popover] made DOM teleportation unnecessary for modals and menus.

Production Pitfalls

Production Pitfall
  • Inherited CSS Breakage: Teleporting a component to document.body detaches it from local CSS custom properties and container queries.
  • Broken Screen-Reader Containment: Forgetting aria-modal or inert on siblings lets keyboard users tab behind the backdrop.
When Not to Use
  • When not to use createPortal: Never reach for createPortal for new modals, drawers, or tooltips, use <dialog>.showModal() or [popover] instead.

Connections & Logical Next Steps

DOM & EventsReact Portals and z-index Layering (Legacy Pattern)
What This Unlocks
Leaf concept

Seen in Architecture Autopsies

Mechanical Comparisons