DOM & EventsBaseline · Widely

The Browser Top Layer

Mental Model

The Browser Top Layer is a render list managed outside normal DOM paint order. Elements promoted via Native Dialog or Popover API paint above every CSS Stacking Context, ignoring ancestor overflow: hidden and z-index.

Interactive Simulator

Stacking Context Clipping vs Top Layer Promotion

Toggle parent transform/overflow clipping against Top Layer promotion to observe z-index isolation.

Z-Order Paint StackTrapped in Parent Context
z-index: 9999Sticky 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 < 9999)
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: 9999)

Under the Hood

The rendering engine maintains the Top Layer as a document-level LIFO ordered set painted after the entire root stacking context. No matter how many overflow: hidden clips or z-index: 99999 contexts exist inside the DOM tree, promoted elements render cleanly above the whole document.

  1. LIFO Ordered Set: The document maintains a top layer list; each showModal() or showPopover() appends to the end, painting last-in on top.
  2. Viewport Containing Block: Top Layer elements escape ancestor transform and clip-path containing blocks.
  3. ::backdrop Layer: Each modal or popover receives its own ::backdrop pseudo-element painted immediately beneath it.
CSS
/* Animating Top Layer entry & exit cleanly */
dialog[open], [popover]:popover-open {
  opacity: 1;
  transform: scale(1);
  transition: opacity 0.2s, transform 0.2s, display 0.2s allow-discrete;
}
@starting-style {
  dialog[open], [popover]:popover-open { opacity: 0; transform: scale(0.96); }
}

Problem Genealogy

  • 2005 (z-index: 999999 Arms Race): Libraries escalated arbitrary z-index constants that still failed inside transform or opacity parents.
  • 2014 (Fullscreen & <dialog>): WHATWG formalized the Top Layer for fullscreen video and modal dialogs.
  • 2024 (Popover API & @starting-style): Opened Top Layer promotion to non-modal tooltips, menus, and toasts with CSS entry transitions.

Production Pitfalls

Production Pitfall
  • z-index Ignored Inside Top Layer: Setting z-index: 99999 on an earlier popover will not raise it above a later popover, order depends strictly on activation order.
  • display: none Breaks Exit Transitions: Closing a Top Layer element snaps it out of the layer unless transition-behavior: allow-discrete is declared.
When Not to Use
  • When not to use Top Layer: Do not promote persistent inline banners or sticky headers; keep them in normal document flow, and use the inert attribute when non-Top-Layer regions must block background focus.

Connections & Logical Next Steps

Seen in Architecture Autopsies

Mechanical Comparisons