The Browser Top Layer
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.
Stacking Context Clipping vs Top Layer Promotion
Toggle parent transform/overflow clipping against Top Layer promotion to observe z-index isolation.
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.
- LIFO Ordered Set: The document maintains a
top layerlist; eachshowModal()orshowPopover()appends to the end, painting last-in on top. - Viewport Containing Block: Top Layer elements escape ancestor
transformandclip-pathcontaining blocks. ::backdropLayer: Each modal or popover receives its own::backdroppseudo-element painted immediately beneath it.
/* 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: 999999Arms Race): Libraries escalated arbitraryz-indexconstants that still failed insidetransformoropacityparents. - 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
z-indexIgnored Inside Top Layer: Settingz-index: 99999on an earlier popover will not raise it above a later popover, order depends strictly on activation order.display: noneBreaks Exit Transitions: Closing a Top Layer element snaps it out of the layer unlesstransition-behavior: allow-discreteis declared.
- 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
Floating popovers and dialogs promote into the browser top layer or portals to escape overflow clipping.
Opening a <dialog> via showModal() automatically marks all non-Top-Layer DOM subtrees inert.
Native Top Layer promotion eliminates the need to teleport DOM nodes to document.body.
Top Layer elements paint in a dedicated layer above the entire document root stacking context.
Top Layer elements and their ::backdrop pseudo-elements paint after all normal compositor layers.
showModal() marks background subtrees inert automatically, whereas custom overlays require the inert attribute explicitly.
Stacking contexts trap z-index inside ancestors, whereas the Top Layer renders above every stacking context.
Seen in Architecture Autopsies
Mechanical Comparisons
Stacking contexts trap z-index inside ancestors, whereas the Top Layer renders above every stacking context.
showModal() marks background subtrees inert automatically, whereas custom overlays require the inert attribute explicitly.