Handoff
Categories

Managing z-index in Large Projects Using Explicit Stacking Context Layers

Organise z-index values in large projects with a custom property scale system and explicit stacking context isolation to prevent the 9999 arms race.

By , Publisher

The wrong assumption that breaks more z-index strategies than any other is that a z-index of 9999 always beats a z-index of 1. It does not. It only beats it when both pieces live in the same stacking context. The moment you put an opacity of 0.5 on a parent, that parent becomes a new stacking context. Every z-index value inside it is now measured against its siblings inside that same parent, not against the whole page. So you can have a modal with z-index: 10 sitting inside a transformed container that renders above your carefully scaled z-index: 1000 header, and you will not understand why until you open DevTools and trace the context. The method that actually works for managing z-index in a large project is not a single property. It is a discipline of naming your stacking contexts, isolating them on purpose, and keeping a scale that everyone on the team can read. That discipline is what this guide gives you. The stacking context surprise is not a bug. It is the CSS layout algorithm being literal about paint order. The fix is not to fight the algorithm. It is to use the tools it gives you to make the order explicit.

Build a Z-Index Scale System

Start with a z-index scale system. Do not invent numbers as you go. Decide once, on the `:root` or inside a dedicated layer, what the highest value in your project is, and what each integer means. A common scale is: base at 0, sticky headers at 100, dropdowns at 200, modals at 1000, and toasts at 1100. You do not need a value above 1100 if you never create more than that many independent contexts. The scale system is not about the size of the number. It is about the semantic meaning attached to each rung. When a new component needs to sit on top, you do not ask 'what number do I use'. You ask 'which rung does this belong on, and is there already something on that rung fighting for the same space'. That question is what prevents the values from climbing to 9999, because nobody knows what else is on the page. Here is a runnable scale system that you can copy into any project, using custom properties so the values are documented in one place and can be overridden per component without touching every rule.

:root {
  /* z-index scale system: every value in the project comes from here */
  --z-index-base: 0;
  --z-index-sticky: 100;
  --z-index-dropdown: 200;
  --z-index-modal: 1000;
  --z-index-toast: 1100;
}

/* usage: an element that needs to be above a sticky header */
.modal {
  position: fixed;
  z-index: var(--z-index-modal);
  /* other modal styles */
}

/* do not hardcode values elsewhere; reference the custom property */
.dropdown-menu {
  position: absolute;
  z-index: var(--z-index-dropdown);
}

Control Where Stacking Contexts Are Created

The scale system only works if you also control where new stacking contexts are created. The most common hidden breaker is the stacking context surprise: a parent with `opacity` less than 1, a `transform`, a `filter`, or a `will-change` property that targets a stacking-context-creating property. According to the CSS Color Module Level 3 and the CSS Transforms Module, any element with `opacity` below 1, a `transform` that is not `none`, a `filter` that is not `none`, or a `will-change` that names one of those properties, establishes a new stacking context. This is not optional and it is not a bug. It is specified behaviour. When that happens, the z-index values of the children of that parent are no longer comparable to the z-index values of the page's top-level stacking context. They are compared within the new context. So a child with `z-index: 1` inside an `opacity: 0.5` parent will paint above a sibling of that parent that has `z-index: 1000`, because the child is in a different context. The child's z-index is only relative to its siblings inside that transformed or faded parent. That is why debugging a z-index issue that involves a `transform` is not about the z-index value at all. It is about finding the ancestor that created the context. The debugger in your browser DevTools shows this. Inspect an element, look at the 'stacking context' badge in the Computed panel or the 'Layers' tab to see which element is the root of the context.

Here is the stacking context surprise in a complete, runnable HTML file. Copy it, open it in your browser, and observe the result. The text inside the transform: scale(1) container is z-index: 1. The text outside is z-index: 1000. Because the container has a transform, it becomes a stacking context. The z-index: 1 is local to that context, so it renders above the z-index: 1000 that is a sibling of the context root. Change the transform to none and watch the order flip.

<!DOCTYPE html>
<html>
<head>
<style>
  .context-creator {
    transform: scale(1); /* this line creates a stacking context */
    background: lightblue;
    padding: 20px;
    margin: 20px;
  }
  .low {
    position: relative;
    z-index: 1;
    background: yellow;
    padding: 10px;
  }
  .high {
    position: relative;
    z-index: 1000;
    background: pink;
    padding: 10px;
    margin-top: -30px; /* overlap the previous block */
  }
</style>
</head>
<body>
  <div class="context-creator">
    <div class="low">I am z-index: 1 but inside a transform</div>
  </div>
  <div class="high">I am z-index: 1000, a sibling of the transform</div>
</body>
</html>

Run that and you will see the yellow box paint above the pink box, even though its z-index is a thousand times smaller. The transform on the parent created a new context, so the z-index: 1 is compared only to the z-index of the siblings inside that same parent, not to the outside. The pink box has a z-index: 1000, but it is in the root stacking context. The yellow box’s context is a child of that root context. The root context’s children are the pink box and the transformed container. The transformed container’s z-index defaults to auto, meaning it does not participate in the root context’s z-index ordering. Its child, the yellow box, paints above the pink box because of the paint order of source. This is the stacking context surprise. It is the reason you cannot debug a z-index problem by looking only at the z-index values. You have to trace the ancestors and find which one has opacity, transform, or filter.

Isolate Contexts on Purpose

The fix for the stacking context surprise is not to remove all transforms or filters. Those properties are essential for animations, visual effects, and performance. The fix is to isolate the context on purpose using the `isolation` property with the value `isolate`. According to the CSS Positioned Layout Module and the CSS Will Change Module, `isolation: isolate` on an element creates a new stacking context for that element and all its children, but it does not change the rendering of the element itself. It is a way to say 'this element and its descendants form a single context, and I want that context to be treated as a unit in the parent context'. This is useful when you have a component that internally uses z-index values, and you do not want those values to leak out and interfere with the rest of the page. By isolating the component, you guarantee that its internal z-index scale is local. You can reason about the component in isolation. The `isolation` fix is the counterpart to the scale system: the scale system names the values, the `isolation` contains them.

Here is the isolation fix applied to the same scenario, making the overlapping behaviour predictable. Add isolation: isolate to the container that has the transform. Now the z-index of the child is still local to that container, but the container itself is a positioned element in its parent context. You can give the container a z-index, and it will participate in the parent context’s ordering. The result is that the z-index: 1 inside the isolated container will not paint above the z-index: 1000 sibling unless the container itself has a z-index that is higher. In this version, the yellow box stays below the pink box because the container has no z-index and defaults to auto, which does not participate in the root context. The isolation makes the boundary explicit. You are never surprised by a transform or opacity creating a context you did not intend.

<!DOCTYPE html>
<html>
<head>
<style>
  .context-creator-isolated {
    transform: scale(1);
    isolation: isolate; /* now the container is a context root, but we control it */
    background: lightblue;
    padding: 20px;
    margin: 20px;
    /* no z-index here, so the container is auto in the root context */
  }
  .low {
    position: relative;
    z-index: 1;
    background: yellow;
    padding: 10px;
  }
  .high {
    position: relative;
    z-index: 1000;
    background: pink;
    padding: 10px;
    margin-top: -30px;
  }
</style>
</head>
<body>
  <div class="context-creator-isolated">
    <div class="low">I am z-index: 1 inside an isolated transform</div>
  </div>
  <div class="high">I am z-index: 1000, and now I win</div>
</body>
</html>

With isolation: isolate, the yellow box stays below the pink box. The isolated container does not have a z-index, so it does not participate in the root context’s z-index ordering. The pink box, with z-index: 1000, wins. If you want the container to be above the pink box, give it a z-index that is higher than 1000. That is now a deliberate choice, not a hidden effect of the transform. The isolation gives you back control. It is the difference between a transform that silently creates a context and a transform that does so while you watch, because you have put isolation on the element that owns the context. Use isolation on any component that has a fixed, absolute, or sticky position and contains items with z-index that should not leak. It is the visual equivalent of a module boundary in JavaScript. A way to encapsulate the stacking context so you can reason about it independently.

Organise the Cascade with Layers

Now that you have a scale and an isolation strategy, the next question is how to organise the cascade itself. This is where cascade layers z-index organisation comes in. Cascade layers, introduced as part of the CSS Cascade 5 specification, give you a way to explicitly order your entire stylesheet into priority buckets, independent of specificity and source order. If you put your z-index scale system and all your component styles into a layer, you can guarantee that your values will not be overridden by a third-party stylesheet that does not use layers. Unlayered styles win over layered styles, and later layers win over earlier layers. This is a powerful tool for managing z-index across a large project. It means you can put your scale system in a layer that is declared before your components, and your components in a layer that is declared before your utilities, and know that your intended z-index values will survive. But layer order is critical. You must declare all your layers at the top of your stylesheet, before any other rules, or the order will be the order you wrote them, not the order you intended.

Here is how you combine the scale system with cascade layers. Notice that the @layer at-rule is used to define the order of all the layers in one place, and then rules are assigned to layers using @layer <name> { ... }. This keeps the z-index values out of the global namespace and inside a named layer that you can reason about. The layer order itself is a form of documentation. It tells any developer reading the file which styles are meant to win.

/* define the layer order once, at the top of your stylesheet */
@layer reset, theme, layout, components, utilities;

@layer theme {
  :root {
    --z-index-base: 0;
    --z-index-sticky: 100;
    --z-index-dropdown: 200;
    --z-index-modal: 1000;
    --z-index-toast: 1100;
  }
}

@layer components {
  .modal {
    position: fixed;
    z-index: var(--z-index-modal);
  }
  .dropdown-menu {
    position: absolute;
    z-index: var(--z-index-dropdown);
  }
}

/* any unlayered style will win over these, so be careful */

The cascade layer approach is not a silver bullet. The most common failure is putting @layer declarations after @import rules. The CSS specification requires that @import rules come before any style rules. If you put @import inside a @layer, it becomes part of that layer’s order. The layer order is determined by the order in which the @layer statements appear, not by the @import. In practice, put all your @layer statements at the top, before any @import, or use @import with a layer() function to assign the imported file to a specific layer. If you do not, you will find that your z-index scale system is overridden by a third-party library because the library’s styles are unlayered and win over your layered styles. The other issue is that cascade layers do not change the stacking context. They only change the cascade priority. You still need the isolation strategy to control where contexts are created. The layer order does not help you if two items in the same layer have z-index values that conflict. Specificity within the same layer still applies. So use layers for priority, isolation for context boundaries, and the scale for values.

Know Every Property That Creates a Context

`opacity`, `transform`, and `filter` are the three properties that create a new stacking context without you asking for it, but there are others. The full list from the CSS specification includes: `position` with a z-index that is not `auto`, `opacity` less than 1, `transform` that is not `none`, `filter` that is not `none`, `perspective`, `clip-path`, `mask`, `mask-image`, `mix-blend-mode`, `will-change` with a value that creates a stacking context, and `isolation: isolate`. Each of these has a different Baseline status, but the pattern is the same. For example, `will-change` is a hint to the browser that a property will change. Setting `will-change: opacity` tells the browser to prepare for the opacity change, which includes creating a stacking context immediately. This is a common source of confusion. Developers use `will-change: transform` to optimise animations and then wonder why their z-index broke. The performance-conscious developer should know that `will-change` is a compositor hint, not a magic bullet. It forces the element onto its own compositor layer, which has a memory cost and should be used sparingly. The `transform` and `opacity` properties are the canonical compositor-safe properties. They can be animated on the GPU without triggering layout or paint, but only if the animation is done via the compositor. `filter` is also compositor-safe in some cases, but it can be expensive if the filter is large.

Debug the Ancestor Chain

Debugging a z-index issue in the browser is not a black art. Open the page, right-click the element that is not on top, and choose Inspect. In the Styles panel, look for the z-index value and the `position` property. If the element has a z-index but no `position`, the z-index is ignored. It only applies to positioned elements. If the element has a `position`, look at the 'parent' section of the Elements panel to see if any ancestor has a `transform`, `opacity`, `filter`, or `isolation`. The DevTools in Chrome, Firefox, and Safari all have a 'Layers' tab or badge that shows the stacking context tree. In Chrome, click the 'Layers' tab, and you will see a tree of all the stacking contexts on the page. Click on each node to highlight it, and you can see which element is the root of the context. This is the fastest way to find the hidden context creator. The same information is in the 'Computed' panel. Search for 'z-index' and you will see the computed value, and a link to the stacking context root. Firefox has a similar feature in the 'Layout' panel. The key is to always check the ancestor chain, not just the element itself.

Choose Your Scale Numbers Wisely

One question that comes up is whether the z-index scale system should use integers or powers of ten. The answer is that the size of the integer does not matter as long as the gaps are large enough to insert values later. A scale of 100, 200, 1000, 1100 has generous gaps, which gives you room to add a rung in between if you need it. A scale of 1, 2, 3, 4 has no room to insert a value without renumbering. The convention of using multiples of ten is a way to keep the gaps visible. The real rule is to avoid using the maximum integer (2147483647). It is a clue that someone is trying to force their way out of a context, and it breaks when a new context resets the local scale. Use a number that is small enough to be readable and large enough to have gaps. The custom property convention makes it easy to change the values in one place if you need to renumber. For pre-2016 browsers that do not support custom properties, you have to fall back to hardcoded values in the rule itself, and accept that the documentation is in the comment, not in the variable name.

Handle Shadow DOM and Iframes

Another practical question is how to handle z-index inside shadow DOM or iframes. Each shadow tree creates a new stacking context boundary. The host element of the shadow tree is the only part that participates in the parent context. If you have a web component with a shadow root, and you want it to appear above the rest of the page, give the host element a z-index and a `position`. Do not give them to the internal elements. The same applies to iframes. The iframe element is a stacking context, and its content cannot escape it. If you have a modal inside an iframe, it will never appear above the page that hosts the iframe. This is a common issue with embedded content and ad tags. The solution is to avoid using iframes for content that needs to overlay the page, or to use a top-level approach like a full-screen fixed position element that is outside the iframe. For shadow DOM, you can use the `::part()` pseudo-element to style the host from outside, but the stacking context boundary remains.

Frequently Asked Questions

Question 1: Why does my z-index: 9999 not work when the element is inside a container with a transform?
Answer: The transform property creates a new stacking context, so the z-index: 9999 is local to that container and cannot compete with elements outside it. The container itself becomes the reference for all its children's z-index values.

Question 2: How do I check which ancestor creates a stacking context in DevTools?
Answer: In Chrome or Firefox, right-click the element and choose Inspect. Go to the Computed tab, search for 'z-index', and look for a 'stacking context' badge. Alternatively, use the Layers tab (Chrome) to see the stacking context tree.

Question 3: What is the difference between isolation: isolate and z-index: 0?
Answer: isolation: isolate creates a new stacking context for the element and its children without requiring a position value, and it does not affect the element's paint order. z-index: 0 also creates a stacking context, but only if the element is positioned; otherwise it is ignored.

Question 4: Can I use z-index: -1 to put an element behind the page background?
Answer: Yes, but only if the element's stacking context is the root context and there is no background on the body. Otherwise, the element will be behind the background of its own stacking context, not the page.

Question 5: Why do two modals with the same z-index sometimes render in the wrong order?
Answer: When two elements have the same z-index, they are painted in source order, so the one later in the DOM appears on top. To control the order, either change the DOM order or give each modal a different z-index from your scale.

Document Your Decisions

The scale system and isolation strategy are the two halves of managing z-index in a large project, but they only work if you also document your decisions. The best documentation is a comment in the code at the top of the file, naming the scale and the rules for creating a new stacking context. For example: 'Use the --z-index-* custom properties from the theme layer. Do not use raw integers. If you need a value above --z-index-toast, add a new custom property to the scale, and do not exceed 2000. Use isolation: isolate on any component that contains multiple z-indexed children.' This is not a nice-to-have. It is the difference between a codebase that people can maintain and one that turns into a pile of 9999s. The comment is a kind of documentation that the code cannot express, and it saves hours of debugging time. The rule of thumb is: if you are writing a z-index value that is not a var() reference, you are doing it wrong.

Use Paint Order to Your Advantage

One more technique that helps is to use the paint order model to your advantage. The painting order of an element is determined by the CSS specification, and it is not purely a function of z-index. The order is: the background and borders of the element that establishes the stacking context, then the background of the child stacking contexts in order of their z-index, then the in-flow non-inline descendant blocks, then the floats, then the inline content, then the positioned elements with `z-index: auto` or `z-index: 0`, then the child stacking contexts with positive z-index. This means that a positioned element with `z-index: 0` paints above a positioned element with `z-index: auto`, even if they are siblings. You can use this knowledge to avoid needing a z-index at all. If you want an element to be above a sibling, give it `position: relative` and `z-index: 0`, and it will paint above a sibling that is positioned but has `z-index: auto`. This is a subtle trick that is often overlooked, and it is part of the reason that the 'just use 9999' approach is fragile.

Reduce the Problem When Debugging

When you are debugging a z-index issue in a large project, the fastest path is to reduce the problem. Isolate the component by copying it into a new HTML file with minimal CSS, and see if the issue reproduces. If it does not, then the problem is in the surrounding page. Likely an ancestor with a stacking context or a cascade layer that is overriding your value. If it does reproduce, then the problem is inside the component, and you can inspect the specific properties. This process of elimination is the same as any debugging: bisect the problem. The other tool is to use the 'composite' view in DevTools, which shows you which elements are on which compositor layers, and which have their own layer. This is especially useful for performance. You can see if an element with `will-change: transform` is creating a new layer that is unnecessarily large. The compositor is a separate thread that is responsible for painting layers and compositing them together, and it is a source of the performance benefits of transforms and opacity. If you have too many layers, you can run out of GPU memory, which causes the browser to repaint more than necessary.

Animate Only Compositor-Safe Properties

In terms of performance, the cost of a stacking context is not the context itself, but the property that creates it. `opacity`, `transform`, and `filter` are all expensive to animate if they cause repaint, and they are all cheap if you can animate them on the compositor. The rule is to animate `transform` and `opacity` only, and to avoid animating `filter`, because `filter` can be expensive. For example, animating a large `box-shadow` is a known performance killer, because `box-shadow` is a paint-time effect. The same applies to `filter`: `blur`, `drop-shadow`, and others are not compositor-safe in the same way that `transform` and `opacity` are. The compositor-safe properties are: `transform`, `opacity`, and sometimes `filter` if the browser has a fast path. Always check the paint rate in DevTools while an animation is running. If the fps drops, look for a property that is not compositor-safe. The `will-change` property is a way to hint the browser to promote an element to its own layer, but overuse can hurt performance because it increases memory usage. Use it only for elements that are likely to change, and remove it when the animation is done.

Z-Index Inside Flex and Grid

The last piece of the puzzle is how to handle the z-index of items inside a flex or grid container. The formatting context of a flex or grid container does not change how z-index works. It still applies to positioned elements. However, flex and grid items have a property called z-index that works the same way, but they also have a default of `auto`. If you want a flex item to be above a sibling, you give it z-index. The key difference is that flex and grid items can have z-index without being positioned. The `display: flex` or `display: grid` on the parent establishes a formatting context that allows z-index to apply to items. This is a common source of confusion. In a regular block layout, you need `position: relative` to use z-index. In flex and grid, you can set z-index on the item. This is useful for overlapping items, but it also means you can create a stacking context with a low z-index value. You need to be aware of that when you are debugging.

To summarise the entire method in one paragraph: use a z-index scale system declared as custom properties, use isolation: isolate to create explicit stacking context boundaries, use cascade layers to control the priority of your z-index rules, and use the browser’s DevTools to debug any surprise by finding the ancestor that created a context. This combination of techniques means that you will never have to use a magic number again, and you will never be surprised by a transform or opacity breaking your design. The scale system protects you from the arms race, and the isolation protects you from the context surprise. The cascade layers protect you from third-party overrides, and the DevTools protect you from confusion. This is not a silver bullet, but it is a system that scales with your project. It is the difference between a z-index that is a mystery and a z-index that is a documented part of your architecture.

Now, there is one more thing that is often taught but is not true. Some say that opacity only creates a stacking context when it is less than 1, and that is correct, but the rule is that the computed value of opacity must be less than 1. So opacity: 1 does not create a context, but opacity: 0.99 does. The same is true for transform: a transform of none does not create a context, but transform: scale(1) does, because the computed value is not none. This is a subtle point that trips up many developers. Similarly, filter: none does not create a context, but filter: blur(0) does. The browser treats the presence of the property, not the actual visual effect, as the trigger. This is why you can have a transform: scale(1) that does not visually change anything, but it still breaks your z-index. The practical takeaway is to avoid adding a transform or opacity to an element unless you intend to create a stacking context. If you do not intend it, use isolation: isolate on a parent to contain the context you just created.

One more false belief is that z-index only works on elements with a position of relative, absolute, fixed, or sticky. That is only true if the element is not a flex or grid item. Flex and grid items can have z-index without a position, because the formatting context of the parent allows it. This is supported in all modern browsers. Check caniuse for the latest support data. The practical implication is that if you are using display: flex and you want to overlap two items, you can use z-index on the items without setting position. This is often used in card designs where you want a badge to appear above the card. The badge is a flex child, and it has z-index: 1, while the card has z-index: 0. The flex container creates a stacking context, and the children are placed according to their z-index. So the badge appears above the card. This is a useful technique, but it also means you have to be careful that a flex container with a z-index on a child creates a stacking context for that child, which can affect the page.

Z-Index in CSS-in-JS

The final topic is how to manage z-index when you are using CSS-in-JS libraries such as styled-components or emotion. These libraries generate a stylesheet at runtime, and they do not change the way z-index works. They can, however, make it harder to debug, because the styles are scattered across the generated CSS. The best practice is to use the same scale system and custom properties in your CSS-in-JS code, and to use the same isolation strategy. The difference is that you can access the custom properties as JavaScript variables, and you can use a theme object to define the scale. For example, in styled-components, you might have a theme object with a `zIndex` property, and you use it as `${({ theme }) => theme.zIndex.modal}`. This keeps the values in one place, but it also means that you need to be consistent across your whole codebase. The same rules apply: do not use raw integers, and do not forget to isolate contexts. The only difference is the syntax for accessing the values.

Your First Five-Minute Refactor

The single most practical thing to do next is to open your current project, find the highest z-index value in your codebase, and ask yourself what it is for. If the answer is not 'this is the modal that must always be on top', then you have a magic number that you need to replace. Replace it with a custom property from your scale, and then add a comment explaining what that rung is for. Do this for every z-index value that is not a `var()` call. Then, take a look at the elements that have a `transform` or `opacity`, and decide if you want them to create a stacking context. If you do not, add `isolation: isolate` to their parent. If you do, leave it, but make sure you know. This five-minute refactoring will save you hours of debugging in the future. It is the difference between a codebase that is a puzzle and a codebase that is a pleasure to work in.