z-index

Basic Syntax

.element {
    position: relative;  /* Required */
    z-index: 10;
}

Without position, z-index does nothing. The default value is auto.

Why z-index Fails — The Position Rule

The #1 reason developers get frustrated with z-index.

/* ❌ Does nothing — element is static */
.box {
    z-index: 100;
}

/* ✅ Works — element is positioned */
.box {
    position: relative;
    z-index: 100;
}

The Defined z-index Scale

Never use random z-index values. Define a scale once and stick to it.

:root {
    --z-base: 0;
    --z-dropdown: 10;
    --z-sticky: 100;
    --z-fixed: 200;
    --z-modal-backdrop: 900;
    --z-modal: 1000;
    --z-popover: 1100;
    --z-tooltip: 1200;
    --z-toast: 1300;
}

.dropdown { z-index: var(--z-dropdown); }
.navbar   { z-index: var(--z-sticky);   }
.modal    { z-index: var(--z-modal);    }
.toast    { z-index: var(--z-toast);    }

This prevents "z-index wars" — the situation where every developer uses bigger numbers than the last one to force elements on top.

Stacking Contexts

A stacking context is a scoped area where z-index values only compete with other elements in the same context.

What creates a stacking context:

• Positioned element with a z-index value other than auto.
• Element with transform, filter, or perspective.
• Element with opacity less than 1.
• Element with mix-blend-mode other than normal.
• Element with isolation: isolate.
• Element with will-change on certain properties.
• Flex or Grid items with z-index other than auto.

Common Real-World z-index Values

/* Dropdown menus */
.dropdown-content {
    position: absolute;
    z-index: 10;
}

/* Sticky header */
.header {
    position: sticky;
    top: 0;
    z-index: 100;
}

/* Fixed sidebar */
.sidebar {
    position: fixed;
    z-index: 200;
}

/* Modal backdrop */
.modal-backdrop {
    position: fixed;
    inset: 0;
    z-index: 900;
}

/* Modal itself */
.modal {
    position: fixed;
    z-index: 1000;
}

/* Toast notification */
.toast {
    position: fixed;
    z-index: 9999;
}

How to Fix z-index Problems

A systematic debugging approach:

1. Check position. The element must have position: relative, absolute, fixed, or sticky.
2. Check the parent's stacking context. Open DevTools and look at the ancestors. If any have transform, filter, opacity: < 1, or a z-index, they create a stacking context.
3. Check sibling order. Elements with the same z-index stack by DOM order. If your element is earlier in the DOM, it's behind.
4. Check for negative z-index ancestors. A parent with negative z-index puts its children behind the parent's siblings.
5. Use the DevTools "Layers" panel. Chrome's Layers panel visualizes stacking contexts and helps spot the culprit.