# <dialog> Element and Native Top Layer vs React Portals and z-index Layering (Legacy Pattern)

- **Canonical URL:** https://frontend.rocks/vs/native-dialog-element-vs-react-portal-zindex-legacy/
- **Relation:** Replaces
- **Last Verified:** 2026-11-15
- **Verdict:** Native showModal() replaces React createPortal and z-index hacks with engine-managed Top Layer and inert.

## Comparison Matrix

| Dimension | <dialog> Element and Native Top Layer | React Portals and z-index Layering (Legacy Pattern) |
| :--- | :--- | :--- |
| **Maturity** | Baseline · Widely | Superseded |
| **Domain** | DOM & Events | DOM & Events |
| **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. |
| **Prerequisites** | None | CSS Stacking Context (Portals only exist to escape local ancestor stacking contexts and overflow clipping.); The Browser Top Layer (Native Top Layer promotion eliminates the need to teleport DOM nodes to document.body.) |
| **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. |

## <dialog> Element and Native Top Layer — Under the Hood
1. `dialog.showModal()` appends the element to the `Document` internal `top layer` list, painted after the root [CSS Stacking Context](/concepts/css-stacking-context).
2. The engine generates a `::backdrop` pseudo-element immediately beneath the dialog inside the same Top Layer.
3. Every node outside the dialog is marked `inert`: pointer clicks, text selection, and keyboard tabbing are blocked natively without global listeners.

```html
<dialog id="confirm-modal">
  <p>Delete production index?</p>
  <form method="dialog">
    <button value="cancel">Cancel</button>
    <button value="confirm">Confirm</button>
  </form>
</dialog>
<script>
  document.getElementById('confirm-modal').showModal();
</script>
```

## React Portals and z-index Layering (Legacy Pattern) — 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>
```

## Interactive Labs & Dissections
- [<dialog> Element and Native Top Layer Lab](https://frontend.rocks/concepts/native-dialog-element/#lab) ([Markdown](https://frontend.rocks/concepts/native-dialog-element.md))
- [React Portals and z-index Layering (Legacy Pattern) Lab](https://frontend.rocks/concepts/react-portal-zindex-legacy/#lab) ([Markdown](https://frontend.rocks/concepts/react-portal-zindex-legacy.md))

## Related Architecture Autopsies
- [Autopsy #05: The z-index 9999 Modal Trap (and Its Native Exit)](https://frontend.rocks/autopsies/zindex-9999-tooltip-war/) ([Markdown](https://frontend.rocks/autopsies/zindex-9999-tooltip-war.md)): Tooltip or modal remains trapped behind a sticky header despite z-index: 9999 while JS positioning thrashes layout.

## Primary Sources
- https://html.spec.whatwg.org/multipage/interactive-elements.html#the-dialog-element
- https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog
- https://react.dev/reference/react-dom/createPortal
