CSS stacking context and z-index

Quick reference for CSS stacking contexts: z-index is a local order, not a global contest, and a stacking context is not the same as a containing block.

リファレンスページの本文は現在英語です。

A stacking context is a local list in which descendants are painted. z-index values are compared inside that list, not against every z-index on the page. A child with z-index: 10 inside a context with z-index: 1 does not paint above a sibling context with z-index: 2. Treating z-index as a global contest, and answering with ever larger numbers, is the usual mistake.

The Position page already records that z-index applies to positioned boxes (and some flex or grid items) and that z-index: auto does not create a new stacking context by itself. The Colors page records that opacity other than 1 creates a stacking context. This page is the composition rule and the difference from a containing block, not a rewrite of position values or of opacity.

Examples are complete HTML and CSS fragments. They were parsed with PostCSS and a selector AST parser for syntax and structure. They were not rendered in a browser here, and this is not a visual paint test.

Official sources: MDN and the CSS specification. Fragments were checked with PostCSS 8 for syntax and structure. That is not a CSS conformance suite, and this is not a browser render or visual test.

CSS reference catalog → · CSS tutorial overview →

z-index is local to a stacking context

The root element forms a stacking context. A new context is created by, among other things, a positioned element whose z-index is not auto, a flex or grid item with a z-index other than auto, opacity other than 1, a transform other than none, and isolation: isolate. Descendants of that element are painted as a group within their parent context.

Once a context exists, a descendant cannot break out of it by using a larger z-index. Raise or isolate the ancestor that formed the context, or restructure the tree, rather than inventing z-index: 9999 on a nested box.

Syntax or propertyInitial / defaultInheritedApplies toNotes
z-indexautonopositioned elements, and flex or grid itemsAn integer creates a stacking context and sets the item’s order inside the parent context. auto uses the element’s order in the painting rules without creating a new context by itself. The Position page states this trigger; this page is the local comparison.
isolationautonoall elementsisolate forces a stacking context without requiring a z-index or a transform. auto does not.

A nested 10 does not beat a sibling context of 2

.one { position: relative; z-index: 1; }
.two { position: relative; z-index: 2; }
.one .high { position: relative; z-index: 10; }

The 10 is compared only inside the z-index: 1 context. It cannot outrank the sibling context whose z-index is 2.

  • This is the stacking-context rule, not a measured paint order from a browser.
html
<section class="parent one">
  <div class="high">z-index 10 inside 1</div>
</section>
<section class="parent two">
  <div class="plain">sibling context 2</div>
</section>
<style>
.parent { position: relative; width: 16rem; font-family: sans-serif; background: #F3EFE4; border: 1px solid #0B5853; }
.one { z-index: 1; }
.two { z-index: 2; }
.high { position: relative; z-index: 10; }
</style>

What this markup means

Both sections are positioned, so their z-index values create two stacking contexts, 1 and 2. The nested .high has z-index: 10, but that 10 is local to .one. Painting .two above .one still paints all of .one, including .high, below .two. Increasing the nested number does not change that. isolation: isolate would also form a context, still without making its descendants globally comparable.

Related: Position (z-index trigger), Display

MDN documentation → · CSS specification →

A stacking context is not a containing block

A containing block is the box against which inset offsets and some percentages are measured. The Position page is the reference for those rules, including the case where a transform creates a containing block for fixed descendants. A stacking context is only about painting order.

Some properties establish both. opacity other than 1 creates a stacking context but does not, by itself, do the transform containing-block job. transform other than none does both. isolation: isolate creates a stacking context without changing position. Keep the two terms distinct even when one declaration happens to trigger both.

Syntax or propertyInitial / defaultNotes
opacity (stacking)1A value other than 1 creates a stacking context, as the Colors page already states. It does not hide that opacity is not a positioning containing-block trigger in the transform sense.
transform (stacking)noneA value other than none creates a stacking context and a containing block for fixed and absolute descendants. Those are two consequences of one property, not one concept.

opacity and isolation stack; transform also forms a containing block

.fade { opacity: 0.9; }
.iso { isolation: isolate; }
.moved { transform: translateX(0); }

The first two rules create stacking contexts only. The third also becomes a containing block for a fixed descendant, which is a different role, documented on the Transforms and Position pages.

  • opacity: 0.9 is deliberately not 1. The Colors page covers descendant fading and pointer events; this example only uses opacity as a stacking trigger.
html
<div class="fade">Faded stacking context</div>
<div class="iso">Isolated stacking context</div>
<section class="moved">
  <div class="pin">Fixed inside a transformed section</div>
</section>
<style>
.fade, .iso, .moved { width: 16rem; font-family: sans-serif; background: #F3EFE4; border: 1px solid #0B5853; }
.fade { opacity: 0.9; }
.iso { isolation: isolate; }
.moved { transform: translateX(0); }
.pin { position: fixed; inset: 0 auto auto 0; }
</style>

What this markup means

opacity: 0.9 and isolation: isolate each form a stacking context. They do not, in this stylesheet, change how a containing block is chosen for positioning. transform: translateX(0) forms a stacking context and, because it is not none, also becomes the containing block for the position: fixed descendant. The same declaration can trigger both mechanisms; the mechanisms are still not interchangeable. For inset math and sticky overflow, stay on the Position page. For the transform trigger itself, stay on the Transforms page.

Related: Colors (opacity stacking), Transforms (new containing block), Position

MDN documentation → · CSS specification →