<dialog> Element and Native Top Layer vs React Portals and z-index Layering (Legacy Pattern)
Native showModal() replaces React createPortal and z-index hacks with engine-managed Top Layer and inert.
Structured Comparison Matrix
| Dimension | <dialog> Element and Native Top Layer | React Portals and z-index Layering (Legacy Pattern) |
|---|---|---|
| Mental Model | HTML primitive placing modals in the browser Top Layer above any z-index, with built-in focus management and Escape key handling. | Legacy pattern reparenting overlays to document.body via createPortal and global z-index scales—now superseded by native Browser Top Layer primitives. |
| Maturity & Domain | Baseline · Widely · DOM & Events Chrome 37+ · Firefox 98+ · Safari 15.4+ | Superseded · DOM & Events Chrome 114+ · Firefox 125+ · Safari 17+ |
| Prerequisites | Foundational primitive | |
| When Not to Use | When not to use <dialog>: For non-modal tooltips or dropdown menus that do not block the background, use the Popover API instead. | When not to use createPortal: Never reach for createPortal for new modals, drawers, or tooltips, use <dialog>.showModal() or [popover] instead. |
Engine Mechanics & Trade-Offs
The Top Layer is painted after every stacking context in the document.
Key Pitfalls: Calling .show() instead of .showModal(): .show() activates neither the Top Layer, nor ::backdrop, nor background inertness, leaving your modal trapped in the same z-index swamp you were trying to escape. Exit animations: dialog.close() switches immediately to display: none; combine @starting-style with transition-behav
createPortal teleports DOM nodes to document.body to escape local overflow clipping, yet still fights global z-index tokens and requires manual focus trapping.
Key Pitfalls: 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.