How do z-index and stacking contexts work?

Question

Accepted Answer

`z-index` controls the **front-to-back** stacking order of overlapping elements — higher values sit on top. But it only works on **positioned** elements, and it operates *within* a **stacking context**, which is the source of most z-index confusion.

```css
.modal   { position: fixed; z-index: 100; }   /* on top */
.overlay { position: fixed; z-index: 99; }    /* just below */
.content { position: relative; z-index: 1; }
```

`z-index` is **ignored** on `position: static` (the default) — the element must be `relative`, `absolute`, `fixed`, or `sticky` for it to apply.

## Stacking contexts — the gotcha

A stacking context is a self-contained "layer." `z-index` values only compete **within the same context** — a child can *never* escape its parent's stacking level, no matter how high its z-index.

```css
.parent-a { position: relative; z-index: 1; }
.parent-b { position: relative; z-index: 2; }

.child-of-a { position: absolute; z-index: 9999; }
/* ❌ child-of-a STILL renders below everything in parent-b, */
/*    because parent-a (z-index 1) is entirely below parent-b (z-index 2). */
```

This is the classic "my z-index: 9999 modal is still behind something" bug — the modal is trapped inside a parent that's on a lower layer.

## What creates a new stacking context

Many properties silently create one, which can trap descendants:

```text
- position + z-index (other than auto)
- opacity less than 1
- transform, filter, will-change
- isolation: isolate
- a flex/grid item with z-index
```

## The fix

```css
/* render the modal at the document root (outside trapping parents) — "portal" */
.isolated { isolation: isolate; } /* deliberately create a context where you want one */
```

In practice, render modals/tooltips at the top of the DOM (React portals) so they aren't trapped in a low-layer parent.

## Why it matters

Stacking contexts explain the most baffling z-index bugs: a huge z-index that still loses because its ancestor is on a lower layer.

Knowing that `opacity`, `transform`, and positioned-z-index create contexts — and that children can't escape them — lets you debug overlay/dropdown ordering and structure your DOM (portals) correctly.