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

- **Canonical URL:** https://frontend.rocks/autopsies/zindex-9999-tooltip-war/
- **Case:** #05
- **Failure Mode:** Main-Thread Freeze
- **Production Symptom:** Tooltip or modal remains trapped behind a sticky header despite z-index: 9999 while JS positioning thrashes layout.
- **Last Verified:** 2026-11-16

## Causal Chain
1. [CSS Stacking Context](https://frontend.rocks/concepts/css-stacking-context.md): Parent properties like opacity < 1 or transform isolate child z-index: 9999 inside a local stacking context.
2. [GPU Compositor Layers and will-change](https://frontend.rocks/concepts/gpu-compositor-layers.md): Applying transform or will-change promotes the parent to a GPU compositor layer, implicitly sealing its stacking context.
3. [React Portals and z-index Layering (Legacy Pattern)](https://frontend.rocks/concepts/react-portal-zindex-legacy.md): Portaling the modal to document.body escapes the parent context but triggers JS scroll listeners and z-index escalation.
4. [The Browser Top Layer](https://frontend.rocks/concepts/browser-top-layer.md): Native dialog.showModal() and popover="manual" render in the browser top layer above all document stacking contexts.
5. [CSS Anchor Positioning](https://frontend.rocks/concepts/css-anchor-positioning.md): CSS anchor() and position-try-fallbacks position and flip tooltips in the layout engine with zero JS reflows.

## 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

---
## Incident Report

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:00**: Grid wrapper GPU promotion ships to production.
- **T+22:00**: Users report row action menus (`z-index: 9999`) rendering behind the `z-index: 10` sticky header.
- **T+55:00**: Team ships a JS `document.body` portal with `scroll` listeners to escape clipping; Android p75 INP jumps from 140 ms to 480 ms.
- **T+90:00**: Performance traces show synchronous `getBoundingClientRect()` reflows on every scroll tick.

## The Red Herring

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

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 Simulator

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.

## Layer Dissection

### 01 → 02: Stacking Contexts Meet GPU Layer Promotion

Under [CSS Stacking Context](/concepts/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](/concepts/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](/concepts/react-portal-zindex-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](/concepts/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](/concepts/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.
