Architecture Autopsies
Case #05Main-Thread Freeze7 min read

Autopsy #05: The z-index 9999 Modal Trap (and Its Native Exit)

Production Symptom

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.

  1. T+00:00Grid wrapper GPU promotion ships to production.
  2. T+22:00Users report row action menus (`z-index: 9999`) rendering behind the `z-index: 10` sticky header.
  3. 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.
  4. T+90:00Performance traces show synchronous `getBoundingClientRect()` reflows on every scroll tick.
REJECTED PATCH

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.

  1. 01Rendering Pipeline
    CSS Stacking Context

    Parent properties like opacity < 1 or transform isolate child z-index: 9999 inside a local stacking context.

  2. 02Rendering Pipeline
    GPU Compositor Layers and will-change

    Applying transform or will-change promotes the parent to a GPU compositor layer, implicitly sealing its stacking context.

  3. 03DOM & Events
    React 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.

  4. 04DOM & Events
    The Browser Top Layer

    Native dialog.showModal() and popover="manual" render in the browser top layer above all document stacking contexts.

  5. 05CSS & Layout
    CSS 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.

  1. A parent card sets opacity: 0.99 or transform, forming a local stacking context.
  2. GPU layer promotion via transform or will-change seals that stacking boundary.
  3. Portaling the element to document.body escapes the trap, but forces synchronous JS getBoundingClientRect() reads on scroll.
  4. Moving the overlay into the browser Top Layer eliminates z-index competition entirely.
  5. 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.

Interactive Simulator

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.

Z-Order Paint StackTrapped in Parent Context
z-index: 10Sticky Header (sibling)Painted above modal
Parent (z: 1)Isolation boundary (opacity: 0.9)
z-index: 9999Child ModalTrapped
New Stacking Context
YES (isolated)
Effective child z-index
Bounded to parent (9999 < 10)
GPU Compositor Layer
Promoted
opacity: 0.9 or active transform creates a stacking context: the child's z-index: 9999 cannot escape above a sibling of the parent.
Parent (z: 1)
Child modal (z-index: 9999)
Sibling Header (z: 10)

Layer-by-Layer Dissection

01 → 02

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.

02 → 03

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 scroll and resize listeners across all scrollable ancestors.
  • Call getBoundingClientRect() on every scroll tick, forcing synchronous style recalculation and layout reflow.
  • Maintain a global z-index token registry (z-modal: 1000, z-popover: 1100) that still collides with third-party widgets.
03 → 04

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.

04 → 05

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

HTML
<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-index escalation for overlays: Render modals and popovers with dialog.showModal() or popover so they paint in the Top Layer rather than competing in document stacking contexts.
  • No getBoundingClientRect() on scroll: Position anchor-relative overlays with anchor-name and position-anchor instead of main-thread scroll listeners.
  • Explicit layer-promotion audits: Never apply will-change: transform or opacity < 1 to layout wrappers without verifying that no non-Top-Layer positioned descendants expect global z-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

Last verified: 2026-11-16