Dokumentacja CSS z przykładami: Z-index w CSS

Q: Dlaczego mój z-index nie działa?

Albo element nie jest pozycjonowany (z-index wymaga position innego niż static albo elementu flex lub grid), albo znajduje się w rodzicu, który tworzy kontekst nakładania o niższej kolejności. Dziecko nigdy nie wzniesie się ponad element, pod którym leży jego kontekst nakładania, bez względu na własny z-index.

Q: Czy z-index działa bez position?

Nie na zwykłych elementach blokowych i inline: position: static go ignoruje. Działa natomiast na elementach flex i grid bez żadnego position.

Co robi z-index

Gdy elementy na siebie nachodzą, z-index decyduje, który jest rysowany z przodu. Wygrywa wyższa liczba. Działa na elementach pozycjonowanych (dowolne position oprócz static) oraz na elementach flex i 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>

Bez z-index elementy występujące później w HTML są rysowane na wcześniejszych, więc C zakryłby B, a B zakryłby A. Wartości z-index odwracają tę kolejność: A jest z przodu, potem C, potem B.

Wartości

Wartość	Znaczenie
`auto` (domyślna)	Układany na poziomie 0 razem z rodzeństwem, nie tworzy kontekstu nakładania
`0`	Poziom 0, ale tworzy kontekst nakładania
Dodatnia liczba całkowita	Przed niższymi wartościami
Ujemna liczba całkowita	Za poziomem 0, a także za treścią rodzica, jeśli to rodzic tworzy kontekst nakładania

Prawidłowe są tylko liczby całkowite: z-index: 1.5 jest ignorowane.

Dlaczego z-index 9999 może przegrać: konteksty nakładania

Wartości z-index nie są porównywane w obrębie całej strony. Elementy są grupowane w konteksty nakładania (stacking contexts), a z-index ustala kolejność tylko wewnątrz tego samego kontekstu. Sam kontekst jest potem umieszczany jako jedna warstwa, według z-index elementu, który go utworzył.

Poniżej niebieskie menu rozwijane ma z-index: 9999, ale znajduje się w nagłówku z z-index: 1. Zielony baner, rodzeństwo tego nagłówka, ma z-index: 2. Cała warstwa nagłówka, razem z menu, leży pod banerem:

<!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>

Kliknij przycisk. Przy z-index: auto nagłówek przestaje tworzyć kontekst nakładania, więc 9999 menu jest porównywane bezpośrednio z 2 banera i menu wychodzi na wierzch. Podniesienie menu do 99999 nigdy by nie pomogło.

Co tworzy kontekst nakładania

Każda z tych właściwości zamienia element we własny kontekst nakładania, zamykając w nim z-index wszystkiego, co jest w środku:

Właściwość	Warunek
`position: relative` lub `absolute`	Z `z-index` innym niż `auto`
`position: fixed` lub `sticky`	Zawsze
Element flex lub grid	Z `z-index` innym niż `auto`
`opacity`	Mniejsze niż 1
`transform`, `scale`, `rotate`, `translate`	Dowolna wartość inna niż `none`
`filter`, `backdrop-filter`	Dowolna wartość inna niż `none`
`isolation`	`isolate`
`mix-blend-mode`	Dowolna wartość inna niż `normal`
`will-change`	Gdy wskazuje którąś z powyższych właściwości
`contain`	`layout` lub `paint` (oraz `strict`, `content`)

Zaskakujące są opacity i transform: dodanie rodzicowi efektu zanikania albo animacji przy najechaniu może nagle schować jego menu rozwijane za następną sekcję.

<!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>

z-index: 10 tooltipa powinien umieścić go nad następną kolumną. Ale opacity: 0.99 robi z pierwszej kolumny kontekst nakładania z z-index auto (poziom 0), a druga kolumna występuje później w HTML na tym samym poziomie, więc jest malowana na całej pierwszej kolumnie, razem z tooltipem. Usuń linię z opacity, a tooltip znów będzie z przodu.

Ujemny z-index

Ujemny z-index umieszcza element za jego rodzeństwem. Jeśli rodzic nie tworzy kontekstu nakładania, element może trafić nawet za tło rodzica, co często zaskakuje. isolation: isolate na rodzicu tworzy kontekst bez żadnego innego efektu wizualnego i zatrzymuje ujemne dziecko w środku:

<!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>

Bez isolation bursztynowa ramka spada za szare tło samego przycisku, więc widać tylko jej krawędź. Z isolation: isolate ramka zostaje w kontekście nakładania przycisku: nad jego tłem, pod jego tekstem.

Skala z-index

Zamiast podbijać liczby, wybierz kilka nazwanych warstw dla całej strony:

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

Większość błędów z warstwami to błędy kontekstów nakładania, a nie liczb, więc mała skala plus isolation: isolate na komponentach, które wewnętrznie używają z-index, rozwiązuje bardzo wiele. z-index potrzebuje pozycjonowania, żeby działać; strona o position to omawia.

Częste błędy

z-index na elemencie static. Dodaj position: relative (albo zrób z niego element flex lub grid).
Podbijanie do 9999. Jeśli rodzic tworzy kontekst nakładania poniżej konkurenta, żadna wartość dziecka nie wygra. Znajdź ten kontekst.
Nowe opacity, transform lub filter na rodzicu, które nagle zamyka w nim menu rozwijane.
Wartości dziesiętne. z-index: 1.5 jest nieprawidłowe.
Oczekiwanie, że z-index: 0 i auto działają tak samo. 0 tworzy kontekst nakładania; auto nie.
Okna modalne w głęboko zagnieżdżonych komponentach. Renderuj je blisko końca <body> (albo użyj górnej warstwy elementu <dialog>), żeby żaden kontekst przodka nie mógł ich uwięzić.

Najczęściej zadawane pytania

Co robi z-index?

Ustala kolejność nakładania elementów, które na siebie nachodzą: wyższa wartość jest rysowana przed niższą w obrębie tego samego kontekstu nakładania. Wartość domyślna to auto, a wartości są liczbami całkowitymi, także ujemnymi.

Dlaczego mój z-index nie działa?

Albo element nie jest pozycjonowany (z-index wymaga position innego niż static albo elementu flex lub grid), albo znajduje się w rodzicu, który tworzy kontekst nakładania o niższej kolejności. Dziecko nigdy nie wzniesie się ponad element, pod którym leży jego kontekst nakładania, bez względu na własny z-index.

Co to jest kontekst nakładania (stacking context)?

Grupa elementów nakładanych razem jako jedna warstwa. Wewnątrz niej dzieci są ułożone według swojego z-index; na zewnątrz cała grupa jest umieszczana według z-index elementu, który ją utworzył.

Co tworzy kontekst nakładania?

Między innymi: element główny, element pozycjonowany z z-index innym niż auto, position: fixed lub sticky, element flex lub grid z z-index, opacity mniejsze niż 1, transform, filter, isolation: isolate oraz will-change wskazujące te właściwości.

Czy z-index działa bez position?

Nie na zwykłych elementach blokowych i inline: position: static go ignoruje. Działa natomiast na elementach flex i grid bez żadnego position.

Powiązane zagadnienia