CSS Z-Index

CSS Z-Index Property

The CSS z-index property helps control the stacking order of elements when they overlap.

Elements can overlap when positioning, transforms, Grid, Flexbox, or other layout techniques place them in the same visual area. The z-index property can determine which element appears in front, but stacking contexts also affect how those values are compared.

Understanding Stacking Order

When elements overlap, the browser follows stacking rules to determine which element is painted in front of another.

For a simple example, two positioned elements can occupy part of the same area.

.box-one {
  position: absolute;
  top: 20px;
  left: 20px;
}
.box-two {
  position: absolute;
  top: 60px;
  left: 60px;
}

If no other stacking rules change the result, elements painted later can appear in front of earlier elements. The z-index property provides more explicit control over their stacking order.

Using z-index

The z-index property accepts an integer or the keyword auto. Within the same stacking context, an element with a higher applicable stack level is generally painted in front of one with a lower stack level.

.box-one {
  position: absolute;
  z-index: 1;
}
.box-two {
  position: absolute;
  z-index: 2;
}

In this example, .box-two appears in front of .box-one where the two boxes overlap, assuming they participate in the same relevant stacking context.

Z-Index Values

The z-index property can use positive integers, zero, negative integers, or auto.

The values do not represent physical distances. A z-index of 1000 does not place an element a measurable distance in front of another element.

Values only need to establish the required stacking relationship within the relevant stacking context.

Elements with the Same Z-Index

When comparable elements have the same stack level, their painting order can depend on the stacking rules and document order.

.box-one,
.box-two {
  position: absolute;
  z-index: 1;
}

In a simple case where both boxes otherwise have the same stacking priority, the element appearing later in the HTML is painted in front.

Assign different z-index values when the visual stacking relationship needs to be explicit.

Negative Z-Index Values

A negative z-index can place an element at a lower stack level within its stacking context.

.background-shape {
  position: absolute;
  z-index: -1;
}

Negative values require care because the element's relationship to its parent stacking context and other backgrounds can make the result different from simply placing it behind one nearby element.

When a decorative element only needs to sit behind content inside a component, creating a controlled stacking context for that component can make the result easier to manage.

Stacking Contexts

A stacking context is a group of elements that is stacked as a unit relative to elements outside that context.

This means a very large z-index on a child cannot automatically place that child above an element belonging to a different stacking context that is itself stacked above the child's parent context.

.parent-one {
  position: relative;
  z-index: 1;
}
.parent-two {
  position: relative;
  z-index: 2;
}
.child {
  position: absolute;
  z-index: 999;
}

If .child belongs to the stacking context created by .parent-one, its value of 999 is resolved within that context. It does not automatically escape its parent and appear above .parent-two.

Creating Stacking Contexts

Several CSS features can create a stacking context. Common examples include a positioned element with a z-index other than auto, fixed or sticky positioning, certain flex and grid items with z-index, and properties such as opacity and transform when used with particular values.

.component {
  position: relative;
  z-index: 0;
}

This positioned element with z-index: 0 establishes its own stacking context, allowing stacking relationships inside the component to be managed without competing directly with every element elsewhere on the page.

Because many CSS features can establish stacking contexts, understanding the ancestor structure is often more useful than continually increasing z-index numbers.

When Z-Index Does Not Work as Expected

A common mistake is assuming that the largest z-index value on the page must appear above everything else.

.child {
  position: absolute;
  z-index: 9999;
}

If the child is inside a stacking context that is below another stacking context, increasing the child's z-index may not change its position relative to that outside context.

When a stacking problem occurs, check the element's ancestors and determine which stacking contexts contain the elements being compared.

Also verify that z-index applies to the element in its current layout situation rather than assuming every element responds identically to it.

Z-Index Best Practices

Use z-index to express meaningful stacking relationships rather than relying on unnecessarily large numbers.

For example, a site might use a small, consistent set of stacking levels for ordinary content, dropdown menus, sticky interface elements, and modal interfaces.

.dropdown {
  z-index: 10;
}
.sticky-header {
  z-index: 20;
}
.modal {
  z-index: 30;
}

The exact numbers are less important than maintaining a predictable relationship between the layers.

When an unexpectedly large value seems necessary, check for an unwanted stacking context before simply increasing the number.

CSS Z-Index Example

The following example contains three overlapping boxes with different z-index values. Open the example in the editor and change the values to see how the stacking order changes.

.box-one {
  z-index: 1;
}
.box-two {
  z-index: 2;
}
.box-three {
  z-index: 3;
}