CSS isolation: give a component a stacking boundary

Last updated: 5 Oct 20265 min read

tutorial

Isolation set to isolate forces an element to form a new stacking context. Descendants can then be ordered within that context without competing directly with elements outside it.

When to use it

A receipt card has a local status badge layered over its header. Isolate the card so a large badge z-index cannot unexpectedly climb above a neighboring dialog. The card still sits in the page's own stacking order; isolation does not make it a modal layer, and a child cannot escape above a sibling context whose whole box is painted later. The sample uses a modest local z-index and a named component class rather than a site-wide number scale. Check the card beside sticky navigation and inside a scroller. If a popover must cross the card boundary, place that popover in an appropriate top layer or layout owner instead of escalating its descendant z-index.

.receipt-card { position: relative; isolation: isolate; }
.receipt-card__status { position: absolute; inset-block-start: .75rem; inset-inline-end: .75rem; z-index: 1; }

Cost and verification

A stacking boundary is cheap by itself, but it can change paint order in ways that surprise a page assembled from independent components. Inspect shadows, tooltips, and focused controls that overlap the edge. Avoid treating z-index as a global priority number: its comparisons are local to a stacking context. Keep ordinary content in document order so the badge's visual placement does not become the only way to understand the status. If blending is involved, test the result against both the card surface and neighboring surfaces before keeping the effect.

Common Mistakes

Do not expect a descendant z-index to escape its parent's stacking context.
Do not use isolation to make an ordinary card behave like a dialog.
Do not place required status text solely in an overlaid badge.

Connected lessons

Further rendering decisions

CSS mix-blend-mode: confine decorative blending to one surface

css

reference

web