CSS stacking contexts: debug overlays without arbitrary z-index inflation

Last updated: 1 Oct 20265 min read

tutorial

A stacking context groups descendants for paint order. A child cannot escape its ancestor's stacking order merely by receiving a very large z-index.

How the rule works

A receipt help panel appears below a fixed header even after its own z-index is raised. The header and panel may belong to different stacking contexts; inspect their ancestors before changing numbers. Positioning with z-index is one cause, and opacity, transforms, and other properties can create contexts too. Use a small documented layer scale for application-owned overlays, and let browser-managed top-layer UI handle modal dialogs where appropriate. A CSS overlay does not trap focus or make the background inert. For a blocking task, use the native dialog behavior instead of painting a high-z box over the page.

.site-header { position: sticky; top: 0; z-index: 20; }
.receipt-help-layer { position: relative; z-index: 30; }
.receipt-help-layer .note { position: absolute; inset-block-start: 100%; }

Cost and verification

Z-index values do not affect transfer size. The cost is debugging and visual overlap across routes, especially when a transformed ancestor changes the containing or stacking context. Inspect computed styles and the element tree, then test zoom and keyboard focus beneath the overlay. The sample's numbers are a local scale, not a universal layering system. If a native popover fits, it may remove some custom stacking work.

Common Mistakes

Do not use z-index: 999999 as the first diagnostic step.
Do not assume a high-z child can outrank an ancestor's context.
Do not confuse paint order with focus or modal behavior.

Connected lessons

Related behavior

CSS isolation: give a component a stacking boundary

Further rendering decisions

css

layout

web