Tutorial

The Mighty CSS z-index Property

CSS

While this tutorial has content that we believe is of great benefit to our community, we have not yet tested or edited it to ensure you have an error-free learning experience. It's on our list, and we're working on it! You can help us out by using the "report an issue" button at the bottom of the tutorial.

In this article, you’ll learn about how to use the z-index CSS property… The only way to break into the 3rd dimension with CSS!

Most of the time when you’re styling things with CSS, it’s on a 2D plane. HTML elements are placed horizontally/vertically on the page like stacking blocks in Tetris. The z-index changes this paradigm and gives you the ability to define a visual hierarchy on the 3rd plane: the z-axis.

Diagram illustrating the Z axis


In this code snippet, the #navbar, will overlap the #footer (if their position overlaps) because it has a higher z-index.

#navbar {
  position: relative;
  z-index: 11;
}

#footer {
  position: relative;
  z-index: 10;
}

If we weren’t using z-index at all, the navbar would simply push the footer away instead of overlapping it.

Uses for z-index

Looking at code by itself is a little bit abstract, so let’s check out this demo where z-index is used.

See the Pen eYZEoVL by alligatorio (@alligatorio) on CodePen.

<div>
  <img src="https://assets.digitalocean.com/articles/docker_node_image/sammy.png" />
</div>
<div id="magazine-title">
  Sammy the Shark
</div>
#portrait {
  position: relative;
  z-index: 1
  width: 200px;
}

#magazine-title {
  position: relative;
  z-index: 2;
  top: -2em;
  left: 2em;
  font: normal 2em sans-serif;
  color: darkslategray;
  background-color: whitesmoke;
  border: 3px dotted darkslategray;
}

Using z-index, we’re able to cause the text to overlap the image! This is just a small way that layers introduce a different way for you to think about web design.

A Minor Caveat

If you have a keen eye, you probably noticed that the previous code snippets used position: relative along with z-index. This was not a coincidence: the z-index rule only works on “positioned elements”.

Forgetting to apply a position rule will effectively ignore the z-index rule.

div {
  position: static | relative | absolute | sticky | fixed;
  z-index: 1;
}

A positioned element is an HTML element that’s either relative, absolute, fixed, or sticky. Basically, it’s anything besides static.

Sibling Rivalry

Another small note is that z-index only competes amongst sibling HTML elements.

Given two HTML elements, the deeply nested HTML element will always get overlapped by a less-nested HTML element with a lower z-index value.

Here is a demo demonstrating that z-index only competes among sibling HTML elements:

<div class="blue">
  <div class="violet"></div>
  <div class="purple"></div>
</div>
<div class="green"></div>
.blue {
  position: relative;
  z-index: 2;
  background-color: blue;
}
.violet {
  position: relative;
  z-index: 4;
  background-color: violet;
}
.purple {
  position: relative;
  z-index: 1;
  background-color: purple;
}
.green {
  position: relative;
  z-index: 3;
  background-color: green;
  top: -4em;
}

The HTML element div.violet will get overlapped by div.green despite having a higher z-index value!

The values for z-index must be an positive/negative integer. This doesn’t mean you can have unlimited z-axis layers! The maximum range is ±2147483647.

In CSS code bases, you’ll often see z-index values of 999, 9999 or 99999. This is a perhaps lazy way to ensure that the element is always on top. It can lead to problems down the road when multiple elements need to be on top. Most of the time you’ll find that a z-index of 1 or 2 will suffice for your needs.

Wrapping Up

Let’s review some of the things we’ve learned about z-index:

  • z-index can create overlapping layers on the z-axis!
  • z-index only works with positioned elements
  • z-index only competes with siblings HTML elements

When you layer content it can create interesting designs! Hopefully you’ve gotten a good idea of how z-index works, and some of the guidelines so you can use it with success!

Visit MDN for in-depth documentation on the z-index property.

Creative Commons License