Why isn't my z-index working? Find the stacking context
z-index: 9999 and it is still underneath? The cause is almost always a stacking context you cannot see. What creates one, how to find the ancestor trapping your element, and three ways to fix it.
By Swapnil Gupta · · 7 min read
A dropdown slides under the section below it. A modal opens behind the sticky header. You raise its z-index to 100, then 9999, then 2147483647, and nothing changes. The number was never the problem: something above your element in the page has fenced it in, and no value inside the fence can climb over it.
The short answer#
Check two things, in this order:
- Is the element positioned?
z-indexdoes nothing on an element withposition: static(the default), unless it is a flex or grid item. Give itposition: relativeif it has none. - Is one of its ancestors a stacking context? If an ancestor has, say, a
transformor anopacitybelow 1, your element'sz-indexonly orders it among that ancestor's descendants. Against the rest of the page, it is only as high as the ancestor.
The second is the one that wastes afternoons. The rest of this guide is about it.
What a stacking context is#
A browser paints a page in layers, and a stacking context is a group of layers that is painted as one unit. Inside it, children are ordered by their z-index. Outside it, the whole group sits at one level, set by the context's own element. A child with z-index: 9999 inside a context at level 0 can never cover a sibling section at level 1, the same way a page in a closed book cannot sit on top of the book next to it.
The dropdown is trapped under the next section. The card is a stacking context at level 0, so its dropdown can never rise above the section's z-index 1.
What creates one (the list people miss)#
The well-known trigger is a positioned element with a z-index. These are the ones that catch people out, because they look like they have nothing to do with stacking:
opacitybelow 1, even0.99transform,translate,scale,rotateorperspectiveset to anything butnone, includingtranslateZ(0)added for smoother animationfilter,backdrop-filter,clip-pathormaskposition: fixedorposition: sticky, with or without az-index- A flex or grid item with a
z-indexother thanauto will-changenaming any of the above,mix-blend-mode,isolation: isolate, andcontainwith layout or paintcontainer-type: sizeorinline-size, used for container queries
MDN keeps the full list. The usual story is that someone adds a fade-in animation or a sticky wrapper to a parent months after the dropdown was built, and the dropdown breaks without anyone touching it.
How to find the context that traps you#
DevTools has no panel that lists stacking contexts. (Microsoft Edge's 3D View comes closest, with a mode that shows them in depth.) The reliable way is to walk up from your element and check each ancestor. Select the element in the Elements panel, then paste this into the Console:
function stackingAncestors(el) {
const found = [];
for (let n = el.parentElement; n; n = n.parentElement) {
const s = getComputedStyle(n);
const why = [];
if (s.position !== "static" && s.zIndex !== "auto") why.push(`z-index ${s.zIndex}`);
if (s.position === "fixed" || s.position === "sticky") why.push(s.position);
if (s.opacity !== "1") why.push(`opacity ${s.opacity}`);
for (const p of ["transform", "translate", "scale", "rotate", "perspective",
"filter", "backdropFilter", "clipPath", "maskImage"])
if (s[p] && s[p] !== "none") why.push(p);
if (s.mixBlendMode !== "normal") why.push("mix-blend-mode");
if (s.isolation === "isolate") why.push("isolation");
if (/paint|layout|strict|content/.test(s.contain)) why.push("contain");
if (s.containerType && s.containerType !== "normal") why.push("container-type");
if (why.length) found.push({ element: n, why: why.join(", ") });
}
return found;
}
stackingAncestors($0);The first entry is the context your element lives in; the one that matters is usually the ancestor that sits beside the element you are losing to. In Nitpique, select the element and open the Stacking section of the Element tab: it shows each context the element is in and why it exists, and what paints beside it in order, so you can see which one wins and press it to select it.
Three ways to fix it#
- Remove or move the trigger. If the ancestor's
transformoropacityis only there for an animation, apply it to an inner element instead, or remove it once the animation ends. - Raise the context, not the child. Give the trapping ancestor a
z-indexhigher than the sibling it loses to. The whole group moves up, dropdown included. - Leave the context entirely. Render the dropdown or modal at the end of
body(a "portal" in React and Vue), or use the browser's top layer: a<dialog>opened withshowModal(), or an element with thepopoverattribute, is painted above every stacking context on the page.
isolation: isolate on purpose. Giving each component its own stacking context means a component's inner z-index values can never leak out and fight the rest of the page, so you can keep them small (1, 2, 3) instead of escalating to 9999.