<dialog> Element and Native Top Layer
Opening a <dialog> via .showModal() promotes the element into the engine's Top Layer, outside every stacking context and overflow: hidden. The rest of the document automatically becomes inert.
Modal: Portal + Focus-Trap vs <dialog>
<Portal>
<div role="dialog" aria-modal="true"
style={{ zIndex: 9999 }}>
{/* + Escape listener + focus trap */}
</div>
</Portal>Remains vulnerable to z-index conflicts across portals.
<dialog ref={ref}>
<form method="dialog">
<button>Close</button>
</form>
</dialog>
// ref.current.showModal()Inertness, Escape, and ::backdrop handled by the engine.
Under the Hood
dialog.showModal()appends the element to theDocumentinternaltop layerlist, painted after the root CSS Stacking Context.- The engine generates a
::backdroppseudo-element immediately beneath the dialog inside the same Top Layer. - Every node outside the dialog is marked
inert: pointer clicks, text selection, and keyboard tabbing are blocked natively without global listeners.
<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>Problem Genealogy
- 2012 (React Portals +
z-index: 9999): Moving modals manually todocument.bodyto escapeoverflow: hidden, a ceremony that only existed because CSS lacked a real Top Layer. - 2018 (
focus-trap+ manualaria-hidden): Fragile JS boilerplate to trap Tab navigation and hide background nodes from screen readers. - 2022+ (
<dialog>Baseline): Top Layer,::backdrop,inert, andEscapedismissal built directly into the engine.
Production Pitfalls
- Calling
.show()instead of.showModal():.show()activates neither the Top Layer, nor::backdrop, nor background inertness, leaving your modal trapped in the samez-indexswamp you were trying to escape. - Exit animations:
dialog.close()switches immediately todisplay: none; combine@starting-stylewithtransition-behavior: allow-discreteto animate exits.
- When not to use
<dialog>: For non-modal tooltips or dropdown menus that do not block the background, use the Popover API instead.
Connections & Logical Next Steps
Reuses the engine's Top Layer mechanism without making the rest of the document inert.
Native <dialog>.showModal() marks background siblings inert in both focus order and the Accessibility Tree.
The Top Layer bypasses the entire stacking context hierarchy and overflow: hidden clipping.
Native showModal() replaces React createPortal and z-index hacks with engine-managed Top Layer and inert.
Mechanical Comparisons
The Top Layer bypasses the entire stacking context hierarchy and overflow: hidden clipping.
Native showModal() replaces React createPortal and z-index hacks with engine-managed Top Layer and inert.