¿Cómo funcionan z-index y stacking contexts?

Question

Accepted Answer

`z-index` controla el orden de apilamiento **de frente a atrás** de elementos superpuestos — los valores más altos se colocan encima. Pero solo funciona en elementos **posicionados**, y opera *dentro de* un **stacking context**, que es la fuente de la mayoría de la confusión con 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` es **ignorado** en `position: static` (por defecto) — el elemento debe ser `relative`, `absolute`, `fixed` o `sticky` para que funcione.

## Stacking contexts — la trampa

Un stacking context es una "capa" independiente. Los valores de `z-index` solo compiten **dentro del mismo contexto** — un hijo nunca puede escapar del nivel de apilamiento de su padre, sin importar cuán alto sea su 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 es el clásico error "mi modal con z-index: 9999 sigue estando detrás de algo" — el modal está atrapado dentro de un padre que se encuentra en una capa inferior.

## Qué crea un nuevo stacking context

Muchas propiedades crean uno silenciosamente, lo que puede atrapar descendientes:

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

## La solución

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

En la práctica, renderiza los modales/tooltips en la parte superior del DOM (React portals) para que no queden atrapados en un padre de capa inferior.

## Por qué es importante

Los stacking contexts explican los errores de z-index más desconcertantes: un z-index gigantesco que sigue perdiendo porque su antepasado está en una capa inferior.

Saber que `opacity`, `transform` y positioned-z-index crean contextos — y que los hijos no pueden escapar de ellos — te permite depurar el orden de superposiciones/desplegables y estructurar correctamente tu DOM (portales).