Contexto de empilhamento CSS: por que seu z-index não funciona

O que é um contexto de empilhamento?

Um contexto de empilhamento é um grupo de elementos pintados juntos como uma unidade. Dentro dele, quem manda é o z-index; fora, o grupo inteiro é posicionado como uma peça só e os filhos não conseguem escapar. Essa frase está por trás de quase todo problema de z-index: um filho com 999999 não está competindo com o resto da página, só com os irmãos dentro do mesmo contexto.

A outra metade da confusão é que muitas vezes o z-index não faz nada. O CSS 2.2 dá à propriedade uma linha de aplica-se a que diz elementos posicionados, então num elemento estático não é uma declaração fraca: ela não é aplicada. É por isso que aumentar o número nunca ajuda.

Esta ferramenta responde às duas perguntas a partir do CSS que você colar, e nomeia a especificação por trás de cada resposta, porque as regras estão espalhadas por sete documentos diferentes e nenhum reúne todas.

Como usar

1. Cole as declarações do elemento. Uma por linha ou separadas por ponto e vírgula. Os três botões de exemplo cobrem os casos mais comuns: um z-index silenciosamente ignorado, uma opacidade que cria um contexto que ninguém espera e um modal fixo que prende tudo que está dentro dele.
2. Diga o que é o pai. Bloco, flex ou grid. Importa mais do que parece: o mesmo z-index é inerte num pai de bloco e funciona num flex ou grid, e esse único controle é a diferença entre as duas respostas.
3. Leia os dois veredictos e depois os motivos. O primeiro diz se o z-index se aplica. O segundo diz se este elemento prende seus descendentes, com cada causa ao lado da especificação que a define.

A exceção de flex e grid que quase todo mundo perde

A regra que as pessoas carregam é que z-index só funciona em elementos posicionados. É quase certa, e a exceção está escrita em duas especificações com as mesmas palavras. O CSS Flexbox diz que, para itens flex, valores de z-index diferentes de auto criam um contexto de empilhamento mesmo que position seja static. O CSS Grid repete a frase exata para itens grid.

Então a mesma declaração se comporta de dois jeitos dependendo do pai. Dentro de um contêiner de bloco normal, um elemento estático com z-index: 999999 é inerte e não cria contexto nenhum. Mova esse elemento para um contêiner flex sem mexer num único caractere do CSS dele e o z-index passa a se aplicar e a criar um contexto. Esta ferramenta tem um controle para o pai só por causa disso: é a única entrada que muda a resposta sem mudar o CSS.

Há uma surpresa gêmea do outro lado. Com z-index em auto, relative e absolute não criam contexto de empilhamento, enquanto fixed e sticky sempre criam. A especificação de posicionamento do CSS diz sem rodeios: caixas com posição fixa ou aderente formam mesmo assim um contexto de empilhamento. Ou seja, metade dos valores de position se comporta de um jeito e metade de outro, justamente no valor que você nunca define de propósito.

A invisível: a opacidade

Das dezessete causas que esta página lista, a opacidade é a que vale decorar, porque nada na tela denuncia. Um elemento com opacity: 0.999 fica exatamente igual a um com opacity: 1 — não dá para distinguir em nenhum nível de zoom — e ainda assim o primeiro cria um contexto de empilhamento e o segundo não. De repente todos os descendentes ficam presos, e um menu que antes aparecia acima do cabeçalho agora aparece atrás.

A mesma armadilha vem em várias outras formas. Um transform de qualquer tipo, um filter, um backdrop-filter, um clip-path, uma máscara, um mix-blend-mode diferente de normal, isolation: isolate, contain com paint ou layout, e will-change citando qualquer uma dessas propriedades criam contexto. Várias são adicionadas por desempenho ou por um efeito de hover, por alguém que não estava pensando em ordem de pintura.

Por isso o conserto de um z-index travado quase nunca é um número maior. É achar o ancestral que está prendendo e decidir se deveria. A ferramenta relata todas as causas que encontra, não a primeira, porque é muito comum um elemento ter três ou quatro ao mesmo tempo e remover só uma não mudar nada.

Limites assumidos

Isto analisa um elemento por vez. O contexto de empilhamento é propriedade de um elemento, mas o problema é propriedade da árvore: para saber se o seu modal está preso é preciso olhar os ancestrais um a um, e a ferramenta não os vê a partir de um único bloco de CSS. O que ela dá é a resposta por elemento, para você subir com ela.

Ela lê as declarações ao pé da letra e não resolve a cascata, propriedades personalizadas, atalhos nem media queries. Se a sua opacidade vem de uma classe que você não colou, ou de um var() definido em outro lugar, ela não tem como saber. Cole os estilos computados do inspetor do seu navegador se quiser certeza.

A lista de causas é o conjunto definido nas especificações citadas ao lado de cada linha, e não está congelada: as especificações do CSS continuam acrescentando. contain e will-change são adições recentes, e não existe um único documento normativo que liste todas — e é exatamente por isso que cada linha traz a própria citação em vez de apontar para uma página só.

Os nomes das especificações ficam em inglês em todas as versões desta página, porque são identificadores de documento e não prosa. Quem for procurar precisa da string que o organismo publicou.

Por que é grátis?

É análise de texto, e roda no seu navegador. Não há servidor envolvido, então não há nada para cobrar nem conta para criar.

Nada é enviado e nada é guardado. Recarregue a página e ela terá esquecido o seu CSS.