Mastering Z-Index: A Comprehensive Guide to Stacking Elements in CSS

As a front-end web developer, you‘ve no doubt encountered perplexing issues with elements overlapping in unexpected ways. You may have tried to solve it by setting a very high z-index value, only to find it doesn‘t work as expected. To really understand how to reliably control the stacking order of elements, you need to understand z-index and stacking context. Let‘s dive in!

What is Z-Index and Stacking Context?

The z-index property in CSS controls the vertical stacking order of elements that overlap. Elements with a higher z-index value are painted in front of elements with a lower z-index value. Z-index seems simple on the surface, but it‘s actually a common source of confusion because it only works within a stacking context.

A stacking context is a three-dimensional conceptualization of elements along a z-axis. Elements in a stacking context are stacked back-to-front according to specific rules. A new stacking context is created in several situations:

• When an element is the root element (HTML)
• When an element has a position value other than static and a z-index value other than auto
• When an element has an opacity value less than 1
• When an element has transform, filter, perspective, clip-path, or mask properties set
• When an element has isolation set to isolate
• On flex items with a z-index value other than auto
• On grid items with a z-index value other than auto

Within a stacking context, child elements are stacked according to these rules:

1. The background and borders of the root element
2. Descendant non-positioned blocks in markup order
3. Descendant positioned elements with negative z-index in z-index order (most negative first)
4. Descendant non-positioned inlines in markup order
5. Descendant positioned elements with z-index:auto or z-index:0 in markup order
6. Descendant positioned elements with positive z-index in z-index order (least positive first)

Let‘s see how these rules play out with some examples.

Default Stacking

By default, in the absence of any z-index or position properties, elements are stacked in the order they appear in the markup. Later elements will appear in front of earlier elements.

<div class="box1">One</div>
<div class="box2">Two</div>
<div class="box3">Three</div>

div {
  width: 60px;  
  height: 60px;
  opacity: 0.7;
}
.box1 { 
  background: blue; 
}
.box2 {
  background: green;  
  margin-top: -40px;
  margin-left: 20px; 
}
.box3 {
  background: red;
  margin-top: -40px;  
  margin-left: 40px;
}

In this example, the boxes will stack in order – blue, green, red – because that‘s the order they appear in the markup.

Z-Index Within a Stacking Context

Adding a z-index value creates a stacking context. Within a stacking context, elements are painted in this order:

• Elements with negative z-index values (most negative first)
• Elements with z-index:auto (default) or z-index:0, in markup order
• Elements with positive z-index values (least positive first)

Let‘s add some z-index values to our example:

<div class="box1">One</div>
<div class="box2">Two</div>
<div class="box3">Three</div>

div {
  position: absolute;  
  width: 60px;
  height: 60px; 
  opacity: 0.7;
}
.box1 {
  background: blue;
  z-index: 3;
}
.box2 {  
  background: green;
  z-index: 2;
  margin-top: 20px; 
  margin-left: 20px;
}
.box3 {
  background: red;  
  z-index: 1;
  margin-top: 40px;
  margin-left: 40px;  
}

Now the boxes stack in z-index order, from highest to lowest: blue, green, red. Note that we had to give the boxes a position value for z-index to have an effect.

Stacking Context Hierarchies

Stacking contexts can be hierarchical. A stacking context contained within another one is termed a child stacking context. The hierarchy of stacking contexts is a subset of the hierarchy of HTML elements because only certain properties create stacking contexts.

<div class="box1">
  <div class="box2">Two</div>
</div>  
<div class="box3">
  <div class="box4">Four</div>
</div>

div {
  position: relative;  
  width: 100px; 
  height: 100px;
  opacity: 0.7;  
}
.box1 {
  background: blue;   
  z-index: 2;
}
.box2 {
  background: green;
  z-index: 10;
  margin-top: 20px;
  margin-left: 20px;  
}
.box3 { 
  background: red;
  z-index: 1;  
}
.box4 {
  background: purple;  
  z-index: 15;
  margin-top: -20px;
  margin-left: 20px;
}

In this example, both box1 and box3 create stacking contexts because they have a z-index set. The z-index of box2 is 10, but it will still display behind box3 because box2‘s stacking context is box1, which has a lower z-index than box3.

Box4 will display in front of box3 because it has a higher z-index value and they are in the same stacking context.

Conceptually, child stacking contexts are flattened into their parent stacking context. The parent establish the ordering of content, and the child establishs the sub-ordering within that content.

Debugging Z-Index Issues

Z-index bugs can be some of the most frustrating to solve in CSS because they often seem nonsensical. Here are some common gotchas to watch out for:

Non-Positioned Elements

One of the most common mistakes is setting a z-index on an element without also giving it a position value. Z-index only works on positioned elements (position:relative, position:absolute, or position:fixed). If you set a z-index on a non-positioned element, it will do nothing.

Unexpected Stacking Contexts

Another common issue is when an element seems to ignore z-index because it‘s in a different stacking context than you expect. This often happens with embedded content like iframes, Flash, and some plugins where the embedded content exists in its own stacking context.

It can also happen if a parent element has properties that create a stacking context, like transform or opacity. In this case, the z-index values of children are scoped within the parent‘s stacking context.

Very High Z-Index Values

It can be tempting to use very high z-index values like 999999 to force an element to the front. However, this is considered a code smell because it‘s often used as a lazy fix for deeper stacking issues. It also creates brittle code where you‘ll need to use even higher values to solve future stacking issues.

Instead, audit your code to understand which elements are creating stacking contexts and how they‘re interacting. The browser DevTools can be helpful for this – Chrome and Firefox have a 3D view that visualizes stacking contexts.

A Better Way to Manage Z-Index

To keep your z-index house in order and avoid these common pitfalls, consider adopting these best practices:

Use Low Values

Prefer using z-index values between -10 and 10. This limited range is easier to keep track of and leaves room for inevitable adjustments. If you find yourself consistently reaching for high values, it‘s a sign that your stacking contexts are getting too complex.

Define Z-Index "Levels"

Instead of sprinkling z-index values throughout your stylesheets, define a set of named "levels" and assign elements to these levels. For example:

$z-indexes: (
  "modal"     : 300,
  "overlay"   : 200,
  "dropdown"  : 100,
  "default"   : 1,
  "below"     : -1,
);

Then reference these levels with a function:

.modal {
  z-index: z(‘modal‘);
}

This makes the stacking relationships more explicit and allows you to change the actual values in one place.

Keep Z-Index Interactions Local

As much as possible, keep elements that need to interact via z-index close together in the HTML and CSS. This locality makes their stacking relationship more obvious and reduces the likelihood of stacking issues creeping in from distant parts of the code.

Use isolation property

If you need to create a new stacking context purely to contain internal z-indexes, consider using the isolation property instead of the traditional position and z-index combo. Setting isolation: isolate creates a new stacking context without any of the side effects of position or z-index.

.dropdown {
  isolation: isolate;
}

This is a cleaner way to create a stacking context when you don‘t actually need to reposition the element.

Conclusion

The interaction of z-index and stacking context can seem byzantine and unpredictable at first glance. But by understanding a few key principles and following best practices, you can tame the chaos and achieve precise control over the stacking order of your elements.

Remember:

• Stacking contexts are created by specific properties like position, z-index, opacity, transform, etc.
• Elements are stacked back-to-front within a stacking context according to specific rules.
• Child stacking contexts are flattened into their parent.
• Z-index only works on positioned elements.

Use z-index sparingly and with care, keep your values low and your interactions localized, and reach for the isolation property when appropriate. With these tools in hand, you‘ll be able to solve those pesky z-index bugs with confidence and style!