CSS z-index and stacking contexts decide what paints on top of what, and almost every z-index bug comes from a stacking context that nobody declared on purpose. Once you can see where those boundaries are, the numbers stop being a guessing game.
The previous lesson in this module covered "When Do sticky and fixed Beat the Alternatives?", and the next lesson in this module is about "What Are the Reliable Ways to Center in CSS Today?".
What does z-index actually control?
z-index sets the painting order of a box among its siblings inside one stacking context. It applies to positioned elements and to flex or grid items, because those two layout modes let items opt into the same ordering without being positioned. On a statically positioned block, z-index is ignored entirely.
The value auto means the element is painted as if it had a z-index of zero, but with one important difference: it does not create a stacking context of its own. Two things with z-index: auto and the same parent are painted in document order, which is why a later element in the markup covers an earlier one even though neither has been given a number.
What creates a stacking context?
A stacking context is a boundary inside which z-index numbers are compared and cannot escape. Several everyday properties create one without you writing z-index at all:
- The root element of the document, which is always one.
- Any element with
position:fixed orposition:sticky. - Any positioned element, plus any flex or grid item, with a
z-indexother than auto. - An element with opacity below 1, or a non-none transform, filter,
backdrop-filter,clip-pathormix-blend-modeother than normal. - An element with
isolation:isolate, or withcontain:layout,contain:paint,contain:content orcontain:strict. - An element whose
will-changenames one of the properties above.
Note that several of these also make the element a containing block for absolutely positioned descendants, which is why an animated or filtered wrapper changes the anchoring of its children as well as their painting order.
In what order does the browser paint a stacking context?
Inside one stacking context the browser paints in a fixed sequence, and z-index only moves an element within the steps that apply to it. The background of the element that forms the context comes first, then child contexts with negative z-index, then ordinary in-flow block descendants, then floats, then inline content, then positioned descendants and child contexts at zero, and finally child contexts with a positive z-index.
This is why a negative z-index does not send an element behind the page background. The background of the context's own element is painted before negative children, so z-index: -1 places the element behind the content of its parent but still in front of that parent's background.
Why does a huge z-index still lose?
Here is the situation that sends people hunting through the stylesheet. A table has a sticky header row, and a row contains a dropdown menu. The menu is given a high z-index, yet it slides underneath the header.
<table class="ledger">
<thead><tr><th scope="col">Invoice</th><th scope="col">Actions</th></tr></thead>
<tbody>
<tr class="ledger-row">
<td>INV-8842</td>
<td>
<button class="menu-trigger" type="button" aria-expanded="false" aria-controls="row-menu">Options</button>
<ul class="row-menu" id="row-menu" hidden>
<li><button type="button">Duplicate</button></li>
<li><button type="button">Archive</button></li>
</ul>
</td>
</tr>
</tbody>
</table>
.ledger-row {
position: relative;
z-index: 1;
}
.row-menu {
position: absolute;
z-index: 50;
}
.ledger thead th {
position: sticky;
top: 0;
z-index: 2;
}
The reason is visible once you find the boundaries. .ledger-row is positioned with a z-index of 1, so it forms a stacking context. The menu at z-index 50 is painted inside that context and never competes with the header directly. The row's context as a whole sits at level 1 in the document's root context, while the sticky header sits at level 2, so the header paints above the entire row, menu included.
How do you fix the order without a war of numbers?
The cheapest fix is to stop creating a stacking context you never needed. The z-index: 1 on the row was probably there to make the row win over something else; if the row only needs position: relative to anchor its menu, drop the number.
.ledger-row {
position: relative;
/* no z-index: the row no longer forms a stacking context */
}
.row-menu {
position: absolute;
z-index: 50;
}
Now the menu participates directly in the root context and outranks the header at level 2. When a component genuinely needs a private layer, say one deliberately, and use isolation: isolate so the intent is visible in the code rather than implied by an opacity value. Isolation does not rescue the menu, because the menu and the header both sit inside the table, but it does stop the table's internal ordering from competing with the layers of the page around it.
/* the table keeps its internal layers to itself */
.ledger {
isolation: isolate;
}
For whole-page ordering, layers are a better tool than numbers because they are declared in one place and cannot be shuffled by accident.
@layer reset, base, components, utilities;
@layer components {
.row-menu {
position: absolute;
z-index: 50;
}
}
The mental model
- Think of z-index as a number inside a box, not a number in the page.
- A stacking context is sealed: nothing inside it can outrank something outside it.
- Opacity, transforms, filters and fixed positioning create boundaries you did not write.
- A positive z-index beats a negative one, but only within the same context.
- Layers give you a deliberate, readable global order; use them before reaching for large numbers.
- Raising the parent's z-index raises everything inside it, which is often what you wanted.
Try it yourself: reproduce the ledger table above and set the menu's z-index to 900 instead of 50, then confirm it still slides under the sticky header. Remove z-index: 1 from .ledger-row and watch the menu rise above the header on its own. Finally, drop the z-index from the row and give it opacity: 0.99 instead, and the menu sinks back under the header, because the row has become a stacking context again just at a lower level.