Stacking context

Stacking context is a three-dimensional conceptualization of HTML elements along an imaginary z-axis relative to the user, who is assumed to be facing the viewport or the webpage. The stacking context determines how elements are layered on top of one another along the z-axis (think of it as the "depth" dimension on your screen). Stacking context determines the visual order of how overlapping content is rendered.

Elements within a stacking context are stacked independently from elements outside of that stacking context, ensuring elements in one stacking context don't interfere with the stacking order of elements in another. Each stacking context is completely independent of its siblings: only descendant elements are considered when stacking is processed.

Each stacking context is self-contained. After an element's contents are stacked, the entire element is considered as a single unit in the stacking order of its parent stacking context.

Within a stacking context, child elements are stacked according to the z-index values of all the siblings. The stacking contexts of these nested elements only have meaning in this parent. Stacking contexts are treated atomically as a single unit in the parent stacking context. Stacking contexts can be contained in other stacking contexts, and together create a hierarchy of stacking contexts.

The hierarchy of stacking contexts is a subset of the hierarchy of HTML elements because only certain elements create stacking contexts. Elements that don't create their own stacking contexts are assimilated by the parent stacking context.

Features creating stacking contexts

A stacking context is formed, anywhere in the document, by any element in the following scenarios:

Nested stacking contexts

Stacking contexts can be contained in other stacking contexts, and they can together create a hierarchy of stacking contexts.

The root element of a document is a stacking context which, in most cases, contains nested stacking contexts, many of which will contain additional stacking contexts. Within each stacking context, child elements are stacked according to the same rules explained in Using z-index. Importantly, the z-index values of its child stacking contexts only have meaning within its parent's stacking context. Stacking contexts are treated atomically as a single unit in the parent stacking context.

To figure out the rendering order of stacked elements along the z-axis, think of each index value as a "version number" of sorts, where child elements represent minor version numbers underneath their parent's major version number.

To demonstrate how the stacking order of each element participates in the stacking order of their ancestor stacking contexts, let's look at an example page with six container elements. There are three sibling <article> elements. The last <article> contains three sibling <section> elements, with the <h1> and <code> of that third article appearing between the first and second sibling <section> elements.

html
<article id="container1">
  <h1>Article element #1</h1>
  <code>
    position: relative;<br />
    z-index: 5;
  </code>
</article>

<article id="container2">
  <h1>Article Element #2</h1>
  <code>
    position: relative;<br />
    z-index: 2;
  </code>
</article>

<article id="container3">
  <section id="container4">
    <h1>Section Element #4</h1>
    <code>
      position: relative;<br />
      z-index: 6;
    </code>
  </section>

  <h1>Article Element #3</h1>
  <code>
    position: absolute;<br />
    z-index: 4;
  </code>

  <section id="container5">
    <h1>Section Element #5</h1>
    <code>
      position: relative;<br />
      z-index: 1;
    </code>
  </section>

  <section id="container6">
    <h1>Section Element #6</h1>
    <code>
      position: absolute;<br />
      z-index: 3;
    </code>
  </section>
</article>

Every container element has an opacity of less than 1 and a position of either relative or absolute set. These property-value pairs create a stacking context when the element has z-index value other than auto.

css
section,
article {
  opacity: 0.85;
  position: relative;
}
#container1 {
  z-index: 5;
}
#container2 {
  z-index: 2;
}
#container3 {
  z-index: 4;
  position: absolute;
  top: 40px;
  left: 180px;
}
#container4 {
  z-index: 6;
}
#container5 {
  z-index: 1;
}
#container6 {
  z-index: 3;
  position: absolute;
  top: 20px;
  left: 180px;
}

The CSS properties for colors, fonts, alignment, and box-model have been hidden for brevity.

The hierarchy of stacking contexts in the above example is as follows:

Root
│
├── ARTICLE #1
├── ARTICLE #2
└── ARTICLE #3
  │
  ├── SECTION #4
  ├────  ARTICLE #3 content
  ├── SECTION #5
  └── SECTION #6

The three <section> elements are children of ARTICLE #3. Therefore, the stacking of the section elements is completely resolved within ARTICLE #3. Once stacking and rendering within SECTION #3 is completed, the whole SECTION #3 element is passed for stacking in the root element with respect to its sibling <article> elements.

By comparing the z-index as "version numbers", we can see how an element with a z-index of 1 (SECTION #5) is stacked above an element with a z-index of 2 (ARTICLE #2), and how an element with a z-index of 6 (SECTION #4) is stacked below an element with a z-index of 5 (ARTICLE #1). SECTION #4 is rendered under ARTICLE #1 because ARTICLE #1's z-index (5) is valid within the stacking context of the root element, while SECTION #4's z-index (6) is valid within the stacking context of ARTICLE #3 (z-index: 4). So SECTION #4 is under ARTICLE #1 because SECTION #4 belongs to ARTICLE #3, which has a lower z-index value (4-6 is less than 5-0).

For the same reason, ARTICLE #2 (z-index: 2) is rendered under SECTION #5 (z-index: 1) because SECTION #5 belongs to ARTICLE #3 (z-index: 4), which has a higher z-index value (2-0 is less than 4-1).

ARTICLE #3's z-index is 4, but this value is independent of the z-index of three sections nested inside it because they belong to a different stacking context.

In our example (sorted according to the final rendering order):

  • Root

    • ARTICLE #2: (z-index: 2), which results in a rendering order of 2-0

    • ARTICLE #3: (z-index: 4), which results in a rendering order of 4-0

      • SECTION #5: (z-index: 1), stacked under an element (z-index: 4), which results in a rendering order of 4-1
      • SECTION #6: (z-index: 3), stacked under an element (z-index: 4), which results in a rendering order of 4-3
      • SECTION #4: (z-index: 6), stacked under an element (z-index: 4), which results in a rendering order of 4-6

    • ARTICLE #1: (z-index: 5), which results in a rendering order of 5-0

Additional examples

Additional examples include a 2-level hierarchy with z-index on the last level, a 2-level HTML hierarchy, z-index on all levels, and a 3-level HTML hierarchy, z-index on the second level.

See also