CSS Z-index – Stacking Order and Stacking Contexts

/* z-index works on positioned elements only */
.box-a {
  position: absolute;
  z-index: 1;      /* below box-b */
}

.box-b {
  position: absolute;
  z-index: 2;      /* above box-a */
}

/* Negative z-index — behind normal flow elements */
.watermark {
  position: absolute;
  z-index: -1;
}

/* z-index: auto — removed from stacking context participation */
.item { position: relative; z-index: auto; }

/* Without z-index on positioned elements:
   later elements in source order appear on top */

/* Without z-index, the second positioned element appears on top */
.red-box  { position: absolute; top: 10px; left: 10px; }
.blue-box { position: absolute; top: 30px; left: 30px; }
/* blue-box appears on top because it's later in the source */

/* Parent creates a stacking context (opacity < 1) */
.parent {
  opacity: 0.99;       /* creates a stacking context! */
  position: relative;
  z-index: 1;
}

/* Child has huge z-index but is trapped inside parent's context */
.modal-inside-parent {
  position: absolute;
  z-index: 9999;       /* only competes within .parent, not the global page */
}

/* An element outside .parent with z-index: 2 will appear ABOVE
   the modal, even though modal has z-index: 9999 */
.outside-element {
  position: relative;
  z-index: 2;          /* beats parent's z-index: 1, so it's on top */
}

/* The most common triggers: */

/* 1. Position + z-index (not auto) */
position: relative; z-index: 1;
position: absolute; z-index: 0;
position: fixed;    /* always creates a context (z-index not needed) */
position: sticky;   /* always creates a context */

/* 2. Opacity less than 1 */
opacity: 0.99;   /* even 0.99 creates a context! */

/* 3. Transform (not none) */
transform: translateX(0);  /* even a no-op transform creates context */
transform: rotate(0deg);

/* 4. Filter (not none) */
filter: blur(0px);

/* 5. will-change targeting an above property */
will-change: transform;
will-change: opacity;

/* 6. isolation: isolate — explicitly create a context */
isolation: isolate;  /* clean way to create a context intentionally */

/* 7. Various others */
mix-blend-mode: /* any value other than normal */;
clip-path: /* any value other than none */;
-webkit-overflow-scrolling: touch;

/* Step 1: Is position set? z-index only works on positioned elements */
.problem-element { position: relative; } /* or absolute/fixed/sticky */

/* Step 2: Is an ancestor creating a stacking context? */
/* Check ancestors for: opacity < 1, transform, filter, will-change */
/* Open DevTools → look for "Stacking Context" badge in Layers panel */

/* Step 3: Is isolation: isolate needed? */
.component { isolation: isolate; }

/* Step 4: Use a z-index scale and stick to it */
:root {
  --z-behind:   -1;
  --z-base:      0;
  --z-raised:    1;
  --z-dropdown: 10;
  --z-sticky:   20;
  --z-fixed:    30;
  --z-overlay:  40;
  --z-modal:    50;
  --z-toast:    60;
  --z-tooltip:  70;
}

/* Define at :root */
:root {
  --z-behind:    -1;   /* watermarks, decorative backgrounds */
  --z-base:       0;   /* default positioned elements */
  --z-raised:     1;   /* slightly elevated cards */
  --z-dropdown: 100;   /* dropdowns, select menus */
  --z-sticky:   200;   /* sticky headers, sticky sidebar */
  --z-fixed:    300;   /* fixed header, fixed fab buttons */
  --z-overlay:  400;   /* modal backdrop/overlay */
  --z-modal:    500;   /* modal dialog */
  --z-toast:    600;   /* toast notifications */
  --z-tooltip:  700;   /* tooltips (always on top) */
}

/* Use in components */
.site-header   { position: sticky; top: 0; z-index: var(--z-sticky); }
.dropdown-menu { position: absolute; z-index: var(--z-dropdown); }
.modal-overlay { position: fixed; inset: 0; z-index: var(--z-overlay); }
.modal         { position: fixed; z-index: var(--z-modal); }
.toast         { position: fixed; z-index: var(--z-toast); }