9.9.1 Specifying the stack level: the 'z-index' property

'z-index'
Value:  auto | <integer> | inherit
Initial:  auto
Applies to:  positioned elements
Inherited:  no
Percentages:  N/A
Media:  visual
Computed value:  as specified

For a positioned box, the 'z-index' property specifies:

  1. The stack level of the box in the current stacking context.
  2. Whether the box establishes a local stacking context.

Values have the following meanings:

<integer>
This integer is the stack level of the generated box in the current stacking context. The box also establishes a local stacking context in which its stack level is '0'.
auto
The stack level of the generated box in the current stacking context is the same as its parent's box. The box does not establish a new local stacking context.

In this section, the expression "in front of" means closer to the user as the user faces the screen.

In CSS 2.1, each box has a position in three dimensions. In addition to their horizontal and vertical positions, boxes lie along a "z-axis" and are formatted one on top of the other. Z-axis positions are particularly relevant when boxes overlap visually. This section discusses how boxes may be positioned along the z-axis.

The order in which the rendering tree is painted onto the canvas is described in terms of stacking contexts. Stacking contexts can contain further stacking contexts. A stacking context is atomic from the point of view of its parent stacking context; boxes in other stacking contexts may not come between any of its boxes.

Each box belongs to one stacking context. Each box in a given stacking context has an integer stack level, which is its position on the z-axis relative to other boxes in the same stacking context. Boxes with greater stack levels are always formatted in front of boxes with lower stack levels. Boxes may have negative stack levels. Boxes with the same stack level in a stacking context are stacked back-to-front according to document tree order.

The root element forms the root stacking context. Other stacking contexts are generated by any positioned element (including relatively positioned elements) having a computed value of 'z-index' other than 'auto'. Stacking contexts are not necessarily related to containing blocks. In future levels of CSS, other properties may introduce stacking contexts, for example 'opacity' [CSS3COLOR].

Each stacking context consists of the following stacking levels (from back to front):

  1. the background and borders of the element forming the stacking context.
  2. the stacking contexts of descendants with negative stack levels.
  3. a stacking level containing in-flow non-inline-level non-positioned descendants.
  4. a stacking level for non-positioned floats and their contents.
  5. a stacking level for in-flow inline-level non-positioned descendants.
  6. a stacking level for positioned descendants with 'z-index: auto', and any descendant stacking contexts with 'z-index: 0'.
  7. the stacking contexts of descendants with positive stack levels.

For a more thorough explanation of the stacking order, please see Appendix E.

The contents of inline blocks and inline tables are stacked as if they generated new stacking contexts, except that any positioned elements and any elements that actually create new stacking contexts take part in the parent stacking context. They are then painted atomically in the inline stacking level.

In the following example, the stack levels of the boxes (named with their "id" attributes) are: "text2"=0, "image"=1, "text3"=2, and "text1"=3. The "text2" stack level is inherited from the root box. The others are specified with the 'z-index' property. 

<code class="html">
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
  <HEAD>
    <TITLE>Z-order positioning</TITLE>
    <STYLE type="text/css">

      .pile {
        position: absolute;
        left: 2in;
        top: 2in;
        width: 3in;
        height: 3in;
      }
    </STYLE>
  </HEAD>
  <BODY>
    <P>
      <IMG id="image" class="pile"
           src="butterfly.png" alt="A butterfly image"
           style="z-index: 1">

    <DIV id="text1" class="pile"
         style="z-index: 3">
      This text will overlay the butterfly image.
    </DIV>

    <DIV id="text2">
      This text will be beneath everything.
    </DIV>

    <DIV id="text3" class="pile"
         style="z-index: 2">

      This text will underlay text1, but overlay the butterfly image
    </DIV>
  </BODY>
</HTML>
</code>

This example demonstrates the notion of transparency. The default behavior of the background is to allow boxes behind it to be visible. In the example, each box transparently overlays the boxes below it. This behavior can be overridden by using one of the existing background properties.