Docs executáveis de CSS: Z-index CSS

Q: O z-index funciona sem position?

Não em elementos block ou inline normais: position: static o ignora. Ele funciona em itens flex e itens grid sem nenhum position.

O que o z-index faz

Quando elementos se sobrepõem, o z-index decide qual é desenhado na frente. O número maior vence. Ele funciona em elementos posicionados (qualquer position exceto static) e em itens flex e grid:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>z-index</title>
  <style>
    body { font-family: system-ui, sans-serif; }
    .stage { position: relative; height: 170px; }
    .card {
      position: absolute;
      width: 130px; height: 100px; padding: 8px;
      color: white; font-weight: 600; border-radius: 8px;
    }
    .a { background: #2563eb; top: 0; left: 0; z-index: 3; }
    .b { background: #16a34a; top: 30px; left: 60px; z-index: 1; }
    .c { background: #f59e0b; top: 60px; left: 120px; z-index: 2; }
  </style>
</head>
<body>
  <div class="stage">
    <div class="card a" id="a">A z-index: 3</div>
    <div class="card b" id="b">B z-index: 1</div>
    <div class="card c" id="c">C z-index: 2</div>
  </div>
</body>
</html>

Sem z-index, os elementos que vêm depois no HTML são desenhados por cima dos anteriores, então C cobriria B e B cobriria A. Os valores de z-index invertem isso: A fica na frente, depois C, depois B.

Os valores

Valor	Significado
`auto` (padrão)	Empilhado no nível 0 com os irmãos, e não cria stacking context
`0`	Nível 0, mas cria um stacking context
Inteiro positivo	Na frente dos valores menores
Inteiro negativo	Atrás do nível 0, e atrás do conteúdo do pai se o pai formar o stacking context

Só inteiros são válidos: z-index: 1.5 é ignorado.

Por que um z-index 9999 pode perder: stacking contexts

Os valores de z-index não são comparados na página inteira. Os elementos são agrupados em stacking contexts (contextos de empilhamento), e um z-index só ordena elementos dentro do mesmo contexto. O contexto em si é então posicionado como uma única camada, usando o z-index do elemento que o criou.

Abaixo, o dropdown azul tem z-index: 9999, mas vive dentro de um cabeçalho com z-index: 1. O banner verde, irmão desse cabeçalho, tem z-index: 2. A camada inteira do cabeçalho, com o dropdown junto, fica abaixo do banner:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Stacking context</title>
  <style>
    body { font-family: system-ui, sans-serif; font-size: 14px; }
    .header {
      position: relative;
      z-index: 1;                 /* creates a stacking context */
      height: 40px; padding: 10px; background: #e5e7eb;
    }
    .dropdown {
      position: absolute;
      top: 40px; left: 20px;
      z-index: 9999;              /* only counts inside .header */
      width: 180px; height: 110px; padding: 8px;
      background: #2563eb; color: white;
    }
    .banner {
      position: relative;
      z-index: 2;
      margin-top: 20px; height: 60px; padding: 10px;
      background: #16a34a; color: white;
    }
    .no-context .header { z-index: auto; }
  </style>
</head>
<body>
  <div id="page">
    <div class="header">Header, z-index: 1
      <div class="dropdown" id="dropdown">Dropdown, z-index: 9999</div>
    </div>
    <div class="banner" id="banner">Banner, z-index: 2</div>
  </div>
  <p><button type="button" id="fix">Set the header's z-index to auto</button> <span id="out"></span></p>
  <script>
    const report = () => {
      const r = document.getElementById('banner').getBoundingClientRect();
      const top = document.elementFromPoint(r.left + 60, r.top + 20);
      document.getElementById('out').textContent = 'On top at the overlap: ' + top.id;
    };
    document.getElementById('fix').addEventListener('click', () => {
      document.getElementById('page').classList.toggle('no-context');
      report();
    });
    report();
  </script>
</body>
</html>

Aperte o botão. Com z-index: auto, o cabeçalho deixa de formar um stacking context, então o 9999 do dropdown é comparado diretamente com o 2 do banner, e o dropdown vem para a frente. Subir o dropdown para 99999 nunca teria ajudado.

O que cria um stacking context

Qualquer um destes transforma um elemento em um stacking context próprio, prendendo o z-index de tudo o que está dentro dele:

Propriedade	Condição
`position: relative` ou `absolute`	Com `z-index` diferente de `auto`
`position: fixed` ou `sticky`	Sempre
Item flex ou grid	Com `z-index` diferente de `auto`
`opacity`	Abaixo de 1
`transform`, `scale`, `rotate`, `translate`	Qualquer valor diferente de `none`
`filter`, `backdrop-filter`	Qualquer valor diferente de `none`
`isolation`	`isolate`
`mix-blend-mode`	Qualquer valor diferente de `normal`
`will-change`	Com qualquer uma das propriedades acima
`contain`	`layout` ou `paint` (e `strict`, `content`)

As surpresas são opacity e transform: acrescentar um fade ou uma animação de hover a um pai pode, de repente, jogar o dropdown dele para trás da seção seguinte.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>opacity creates a context</title>
  <style>
    body { font-family: system-ui, sans-serif; font-size: 14px; }
    .row { display: flex; gap: 0; }
    .col { position: relative; width: 160px; height: 120px; padding: 8px; background: #e5e7eb; }
    .col + .col { background: #fde68a; }
    .tip {
      position: absolute; top: 40px; left: 100px; z-index: 10;
      width: 120px; padding: 8px; background: #2563eb; color: white;
    }
    .faded { opacity: 0.99; }
  </style>
</head>
<body>
  <div class="row">
    <div class="col faded" id="first">opacity: 0.99
      <div class="tip" id="tip">Tooltip z-index: 10</div>
    </div>
    <div class="col" id="second">Next column</div>
  </div>
  <p id="out"></p>
  <script>
    const r = document.getElementById('second').getBoundingClientRect();
    document.getElementById('out').textContent =
      'On top in the overlap: ' + document.elementFromPoint(r.left + 30, r.top + 60).id;
  </script>
</body>
</html>

O z-index: 10 do tooltip deveria colocá-lo acima da coluna seguinte. Mas opacity: 0.99 transforma a primeira coluna em um stacking context com z-index auto (nível 0), e a segunda coluna vem depois no HTML no mesmo nível, então é pintada por cima da primeira coluna inteira, tooltip incluído. Apague a linha do opacity e o tooltip volta para a frente.

z-index negativo

Um z-index negativo coloca o elemento atrás dos irmãos. Se o pai não forma um stacking context, ele pode ir até para trás do fundo do pai, uma surpresa comum. isolation: isolate no pai cria um contexto sem nenhum outro efeito visual e mantém o filho negativo dentro dele:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Negative z-index</title>
  <style>
    body { font-family: system-ui, sans-serif; font-size: 14px; display: flex; gap: 24px; }
    .button {
      position: relative;
      padding: 14px 20px; background: #e5e7eb; font-weight: 600;
    }
    .button::before {
      content: "";
      position: absolute; inset: -6px;
      background: #f59e0b;
      z-index: -1;               /* behind the button's text */
    }
    .isolated { isolation: isolate; }
  </style>
</head>
<body>
  <div class="button">No isolation</div>
  <div class="button isolated">isolation: isolate</div>
</body>
</html>

Sem isolation, a moldura âmbar cai para trás do próprio fundo cinza do botão, e só a borda dela aparece. Com isolation: isolate, a moldura fica dentro do stacking context do botão: acima do fundo, abaixo do texto.

Uma escala de z-index

Escolha algumas camadas com nome para o site inteiro, em vez de ir aumentando os números:

:root {
  --z-dropdown: 10;
  --z-sticky: 20;
  --z-overlay: 30;
  --z-modal: 40;
  --z-toast: 50;
}
.modal { position: fixed; z-index: var(--z-modal); }

A maioria dos bugs de camadas é bug de stacking context, não de número, então uma escala pequena mais isolation: isolate nos componentes que usam z-index por dentro resolvem muita coisa. O z-index precisa de posicionamento para funcionar; a página de position trata disso.

Erros comuns

z-index em um elemento static. Acrescente position: relative (ou faça dele um item flex ou grid).
Subir para 9999. Se um pai forma um stacking context abaixo do concorrente, nenhum valor no filho vence. Encontre o contexto.
Um novo opacity, transform ou filter em um pai que de repente prende o dropdown dele.
Valores decimais. z-index: 1.5 é inválido.
Esperar que z-index: 0 e auto se comportem igual. 0 cria um stacking context; auto não.
Modais dentro de componentes muito aninhados. Renderize-os perto do fim do <body> (ou use a top layer do elemento <dialog>), para que nenhum contexto ancestral os prenda.

Perguntas frequentes

O que o z-index faz?

Define a ordem de empilhamento de elementos sobrepostos: um valor maior é desenhado na frente de um menor dentro do mesmo stacking context. O padrão é auto, e os valores são números inteiros, inclusive negativos.

Por que meu z-index não funciona?

Ou o elemento não está posicionado (o z-index precisa de um position diferente de static, ou de um filho flex ou grid), ou ele está dentro de um pai que forma um stacking context com ordem mais baixa. Um filho nunca consegue subir acima de um elemento que fica acima do stacking context dele, seja qual for o próprio z-index.

O que é um stacking context?

Um grupo de elementos empilhados juntos como uma única camada. Dentro dele, os filhos são ordenados pelo z-index; fora dele, o grupo inteiro é posicionado pelo z-index do elemento que o criou.

O que cria um stacking context?

Entre outros: o elemento raiz, um elemento posicionado com z-index diferente de auto, position: fixed ou sticky, um filho flex ou grid com z-index, opacity abaixo de 1, transform, filter, isolation: isolate e will-change com essas propriedades.

O z-index funciona sem position?

Não em elementos block ou inline normais: position: static o ignora. Ele funciona em itens flex e itens grid sem nenhum position.

Conceitos relacionados