Como funcionam z-index e stacking contexts?

Question

Accepted Answer

`z-index` controla a ordem de empilhamento **de frente para trás** de elementos sobrepostos — valores mais altos ficam em cima. Mas funciona apenas em elementos **positioned** e opera *dentro* de um **stacking context**, que é a fonte da maioria da confusão com z-index.

```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` é **ignorado** em `position: static` (o padrão) — o elemento deve ser `relative`, `absolute`, `fixed` ou `sticky` para que funcione.

## Por que isso importa

Um stacking context é uma "camada" auto-contida. Valores de `z-index` competem apenas **dentro do mesmo contexto** — um filho nunca pode escapar do nível de empilhamento de seu pai, não importa o quão alto seja o 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). */
```

Este é o clássico bug "meu z-index: 9999 modal ainda está atrás de algo" — o modal está preso dentro de um pai que está em uma camada mais baixa.

## O que cria um novo stacking context

Muitas propriedades silenciosamente criam um, o que pode prender descendentes:

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

## A solução

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

Na prática, renderize modais/tooltips no topo do DOM (React portals) para que não fiquem presos em um pai de camada mais baixa.

## Por que isso importa

Stacking contexts explicam os bugs de z-index mais confusos: um z-index gigantesco que ainda perde porque seu ancestral está em uma camada mais baixa.

Sabendo que `opacity`, `transform` e positioned-z-index criam contextos — e que filhos não podem escapar deles — você pode depurar a ordem de overlay/dropdown e estruturar seu DOM (portals) corretamente.