Tailwind CSS - Z-Index

Modern Guide to Tailwind CSS: Z-Index

The z-index property controls the vertical stacking order of elements that overlap. An element with a higher z-index will appear in front of an element with a lower one. Tailwind CSS provides a set of z-* utilities to manage this stacking order in a systematic way.

Key Concept: Stacking Context

This is the most important concept for understanding z-index. A z-index value only has meaning within a stacking context. An element must be ‘positioned’ (i.e., its CSS position is relative, absolute, fixed, or sticky) to accept a z-index value. Furthermore, properties like opacity < 1, transform, or filter can also create a new stacking context, which can sometimes lead to unexpected behavior.

Z-Index Utilities

Tailwind provides a default scale designed for common UI components like dropdowns, modals, and tooltips.

Class	CSS Properties
z-0	z-index: 0;
z-10	z-index: 10;
z-20	z-index: 20;
z-30	z-index: 30;
z-40	z-index: 40;
z-50	z-index: 50;
z-auto	z-index: auto;

Practical Application: Overlapping Profile Avatars

This example demonstrates how to create a stack of overlapping avatars, a common UI pattern. Each avatar needs to be positioned, and then z-index is used to control which one appears on top.

<!-- Assumes a standard Tailwind CSS project setup -->
<div class="flex items-center justify-center bg-gray-100 p-16">
  <!-- The container establishes a shared coordinate system -->
  <div class="relative flex items-center h-20">

    <!-- Each avatar is positioned absolutely within the container -->
    <img class="h-16 w-16 rounded-full border-4 border-white object-cover
                absolute left-0 z-30"
         src="/path/to/avatar1.jpg" alt="User 1">

    <img class="h-16 w-16 rounded-full border-4 border-white object-cover
                absolute left-10 z-20"
         src="/path/to/avatar2.jpg" alt="User 2">

    <img class="h-16 w-16 rounded-full border-4 border-white object-cover
                absolute left-20 z-10"
         src="/path/to/avatar3.jpg" alt="User 3">

    <div class="h-16 w-16 rounded-full bg-blue-500 text-white
                flex items-center justify-center font-bold
                absolute left-32 z-0 border-4 border-white">
      +5
    </div>

  </div>
</div>

Negative and Arbitrary Z-Index Values

Tailwind supports negative z-index values by prefixing the class with a dash, like -z-10. This is useful for placing decorative elements behind their parent container. For one-off values, especially for modals or overlays that must be on top, you can use arbitrary values.

<!-- A decorative blob positioned behind the content -->
<div class="absolute top-0 right-0 w-48 h-48 bg-purple-200 rounded-full -z-10"></div>

<!-- A modal overlay that must be on top of everything -->
<div class="fixed inset-0 bg-black/50 z-[999]"></div>

Common Errors and Best Practices

• Best Practice: Use the provided z-index scale (10, 20, 30…) to manage stacking for your core UI components. Avoid using arbitrary high numbers like z-[99999] as it’s a sign that your stacking contexts are not well-managed.
• Best Practice: Create a new stacking context on a component’s wrapper (position: relative) to contain its children’s z-index values. This prevents them from interfering with other components on the page.
• Common Error: Applying z-10 to an element that is not positioned (i.e., its position is the default static). The z-index property will be ignored.
• Debugging Tip: If an element with a high z-index is appearing behind another element, the most likely cause is that they are in different stacking contexts. Use your browser’s dev tools to inspect the parents of both elements. Look for any ancestors with properties like opacity, transform, filter, or position: relative that might be creating a new, lower stacking context.