Autopsy #05: The z-index 9999 Modal Trap (and Its Native Exit)
Tooltip or modal remains trapped behind a sticky header despite z-index: 9999 while JS positioning thrashes layout.
The Incident & The False Culprit
A minor UI polish PR added opacity: 0.99 and transform: translateZ(0) to the data-grid wrapper to smooth out horizontal scroll jitter. Storybook visual snapshots passed cleanly.
Within two hours of release, customer support reported unusable row-action menus clipped beneath the position: sticky; z-index: 10 page header, while Android RUM telemetry flagged severe scroll-time INP spikes.
- T+00:00Grid wrapper GPU promotion ships to production.
- T+22:00Users report row action menus (`z-index: 9999`) rendering behind the `z-index: 10` sticky header.
- T+55:00Team ships a JS `document.body` portal with `scroll` listeners to escape clipping; Android p75 INP jumps from 140 ms to 480 ms.
- T+90:00Performance traces show synchronous `getBoundingClientRect()` reflows on every scroll tick.
The Red Herring — Why the First Reflex Failed
The first Slack reflex was to bump the menu's stylesheet from z-index: 9999 to z-index: 2147483647 and add will-change: transform to the table wrapper to "fix scroll jank." Both changes passed local visual checks on an un-scrolled viewport.
In production, z-index: 2147483647 remained trapped beneath the z-index: 10 sticky header. z-index only orders siblings inside the same stacking context, and will-change: transform sealed a new stacking context around the table wrapper.
Causal Chain Traversed
Step-by-step propagation across atomic concepts. Hover or click any step to inspect the underlying mechanism.
- 01Rendering PipelineCSS Stacking Context
Parent properties like opacity < 1 or transform isolate child z-index: 9999 inside a local stacking context.
- 02Rendering PipelineGPU Compositor Layers and will-change
Applying transform or will-change promotes the parent to a GPU compositor layer, implicitly sealing its stacking context.
- 03DOM & EventsReact Portals and z-index Layering (Legacy Pattern)
Portaling the modal to document.body escapes the parent context but triggers JS scroll listeners and z-index escalation.
- 04DOM & EventsThe Browser Top Layer
Native dialog.showModal() and popover="manual" render in the browser top layer above all document stacking contexts.
- 05CSS & LayoutCSS Anchor Positioning
CSS anchor() and position-try-fallbacks position and flip tooltips in the layout engine with zero JS reflows.
This failure combines CSS paint-order isolation with main-thread layout thrashing caused by JavaScript workarounds.
- A parent card sets
opacity: 0.99ortransform, forming a local stacking context. - GPU layer promotion via
transformorwill-changeseals that stacking boundary. - Portaling the element to
document.bodyescapes the trap, but forces synchronous JSgetBoundingClientRect()reads on scroll. - Moving the overlay into the browser Top Layer eliminates
z-indexcompetition entirely. - CSS Anchor Positioning replaces the JS positioning loop with native layout-engine constraint resolution.
Failure Reproduction Lab
Use the stacking context simulator below to test why z-index: 9999 loses to a sibling with z-index: 10. Toggle transform: translateZ(0) or lower opacity below 1 on the parent container, then observe the effective child z-index readout.
Stacking Context Trap & z-index: 9999 Isolation
Adjust parent opacity, transform promotion, and sibling header z-index to observe how a local stacking context traps z-index: 9999.
Layer-by-Layer Dissection
Stacking Contexts Meet GPU Layer Promotion
Under CSS Stacking Context rules, z-index is never global. It only compares siblings that share the same parent stacking context. When a parent container has z-index: 1 and forms a stacking context, a child with z-index: 9999 still paints behind a sibling header at z-index: 10.
Under GPU Compositor Layers, adding transform: translateZ(0) or will-change: transform instructs Blink to promote the element into its own compositor texture. The CSS specification mandates that any element with a non-none transform, filter, or opacity < 1 establishes a new stacking context so the GPU can composite it atomically.
Why React Portals Escalate to Main-Thread Freeze
To escape the parent's stacking context, teams reach for React Portal Z-Index Legacy patterns that render the tooltip directly under document.body. Detaching the overlay from its trigger DOM subtree breaks CSS layout inheritance and forces a JS positioning library to:
- Attach
scrollandresizelisteners across all scrollable ancestors. - Call
getBoundingClientRect()on every scroll tick, forcing synchronous style recalculation and layout reflow. - Maintain a global
z-indextoken registry (z-modal: 1000,z-popover: 1100) that still collides with third-party widgets.
Escaping Document Z-Index via the Top Layer
The Browser Top Layer is a dedicated rendering stratum managed by the user agent outside the document root stacking context.
Elements promoted via dialog.showModal() or the HTML popover attribute (popover="auto" or popover="manual") paint in the Top Layer in last-in-first-out (LIFO) order. No z-index, opacity, overflow: hidden, or transform anywhere in the ancestor tree can clip or occlude a Top Layer element.
Replacing JS Positioning Loops with CSS Anchor Positioning
Placing a tooltip in the Top Layer solves occlusion, while CSS Anchor Positioning eliminates JavaScript coordinate tracking.
Declaring anchor-name: --trigger on the button and position-anchor: --trigger on the popover lets the layout engine compute anchor(bottom) and flip via @position-try inside the standard layout phase, running zero scroll listeners on the main thread.
Architectural Fix & Invariants
<button popovertarget="row-menu" style="anchor-name: --row-btn;">Actions</button>
<div id="row-menu" popover="auto" class="anchored-menu">
<button type="button">Edit Record</button>
</div>
<style>
.anchored-menu {
position: fixed;
position-anchor: --row-btn;
top: anchor(bottom);
left: anchor(left);
position-try-fallbacks: flip-block, flip-inline;
margin: 0;
}
</style>Architectural Invariants:
- Zero
z-indexescalation for overlays: Render modals and popovers withdialog.showModal()orpopoverso they paint in the Top Layer rather than competing in document stacking contexts. - No
getBoundingClientRect()on scroll: Position anchor-relative overlays withanchor-nameandposition-anchorinstead of main-thread scroll listeners. - Explicit layer-promotion audits: Never apply
will-change: transformoropacity < 1to layout wrappers without verifying that no non-Top-Layer positioned descendants expect globalz-index.
Golden Rule: Adding nines to z-index is shouting inside a soundproof room; promote overlays to the Top Layer with popover and anchor them in CSS.
Primary Sources
- https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context
- https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/popover
- https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_anchor_positioning
- https://fullscreen.spec.whatwg.org/#top-layer
Last verified: 2026-11-16