GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing drafts.csswg.org — CSS Positioned Layout Module Level 4

1. Introduction

This is an early delta spec over [css-position-3].

2. Scrollable Containing Block

When a scroll container establishes an absolute positioning containing block for an absolutely positioned box, one of three possible containing blocks are used:

fixed containing block

The fixed containing block of a scroll container corresponds to the scrollport, i.e. the inner padding box edges of the scroll container, but scrolling with the outer context, not the scroll container’s contents.

The fixed containing block established by the document is the fixed positioning containing block.

local containing block

The local containing block of a scroll container corresponds to the padding box edges of the scroll container, but is affixed to the scrollable overflow area, and scrolls with the scroll container’s contents.

The local containing block established by the document is the initial containing block.

scrollable containing block

The scrollable containing block of a scroll container corresponds to the padding edge of the scroll container’s scrollable overflow area, i.e. the outer edge of the padding surrounding its content when determining the extent of its scrollable overflow area. See CSS Overflow 3 § 2.2 Scrollable Overflow. In all cases the scrollable containing block at least encompasses the local containing block.

Note: This includes floats, but ignores absolutely positioned descendants, content overflowing descendant boxes, and the effects of relative positioning and transforms, which do otherwise extend the scrollable area to display them.

The scrollable containing block established by the document is the union of the initial containing block and the margin box of the root element’s generated box.

Note: While all of these are in some sense corresponding to the padding box, they do not coincide for boxes with scrollable overflow.

Figure out the exact concepts needed for top layer. They probably want to do something a tiny bit different, specific to their layer.

Unless otherwise specified, absolutely positioned boxes use the local containing block. Certain CSS features can specify a different containing block. For example, fixed-positioned boxes typically use the document’s fixed containing block, and position-area values other than none can opt absolutely positioned boxes into the scrollable containing block.

Note: There is not currently any way to refer to a fixed containing block other than the fixed positioning containing block, but one might be added in the future.

3. Top Layer

Documents have a top layer, an ordered set containing elements from the document. Elements in the top layer do not lay out normally based on their position in the document; instead they generate boxes as if they were siblings of the root element. Top layer elements are rendered in the order they appear in the top layer; the last element in the top layer is rendered on top of everything else.

Note: This special rendering behavior ensures that elements in the top layer cannot be clipped by anything in the document, or obscured by anything except elements later in the top layer. This ensures that things like popovers can be displayed reliably, regardless of what their ancestor elements might be doing.

The top layer root of an element is its nearest ancestor element that is in the top layer, or none otherwise (in which case it’s painted as part of the document as normal).

Two elements are in the same top layer if they have the same top layer root (including if both are none). An element A is in a higher top layer than an element B if A has a top layer root, and either B has a top layer root earlier in the top layer than A’s, or B doesn’t have a top layer root at all.

Note: The top layer is managed entirely by the user agent; it cannot be directly manipulated by authors. This ensures that "nested" invocations of top-layer-using APIs, like a popup within a popup, will display correctly.

Note: The top layer interacts with the overlay property in a somewhat unusual way. See overlay for details.

Documents also have a pending top layer removals ordered set, containing elements that are pending removal. (See the algorithms, below, for details on how this is used.)

The top layer (and the pending top layer removals) should not be interacted with directly by specification algorithms. (Individual features using the top layer might have ownership over various things in the top layer, like a popover inside of a popover, that need to be reordered or moved as a group.) Instead, specifications should use the following algorithms.

3.1. Top Layer Styling

Every element rendered in the top layer, as well as its corresponding ::backdrop pseudo-element, are rendered with the following qualities:

It generates a new stacking context.
Its parent stacking context is the root stacking context.
It is rendered as an atomic unit as if it were a sibling of the document’s root.

Note: Ancestor elements with overflow, opacity, mask, etc. cannot affect it.
If its position property computes to fixed, its containing block is the viewport; otherwise, it’s the initial containing block.
If it is an element, it and its ::backdrop pseudo-element are not rendered if its shadow-including inclusive ancestor has the display: none.
If its specified display property is contents, it computes to block.
If its specified position property is not absolute or fixed, it computes to absolute.
Unless overridden by another specification, its static position for left, right, and top is zero.

3.2. The ::backdrop Pseudo-Element

Each element rendered in the top layer has a ::backdrop pseudo-element, for which it is the originating element.

When its computed content value is not none, ::backdrop pseudo-elements generate boxes as if they were siblings of the root element. They’re automatically rendered as a separate item in the top layer, below their originating element. (See "paint a document" for details.)

Note: The ::backdrop pseudo-element can be used to create a backdrop that hides the underlying document for an element in a top layer (such as an element that is displayed fullscreen).

The ::backdrop pseudo-element is a fully styleable pseudo-element.

User agents should contain the following rules in a UA-level style sheet:

::backdrop {
  position: fixed;
  inset: 0;
}

Other specifications can additional properties to the default ::backdrop rendering.

Note: For example, a fullscreen element (see [FULLSCREEN]) styles its ::backdrop as opaque black by default.

See § 3.1 Top Layer Styling for additional details on how ::backdrop elements are rendered.

3.3. Top Layer Manipulation

An element el is in the top layer if el is contained in its node document’s top layer but not contained in its node document’s pending top layer removals.

Note: Specs should use this concept, rather than rendered in the top layer, when they are manipulating the top layer itself. Using this concept avoids the behavior being different based on whether there’s an overlay transition, or whether two operations happened between rendering updates or across them.

An element el is rendered in the top layer if el is contained in its node document’s top layer, and el has overlay: auto.

Note: Specs should use this concept, rather than in the top layer, when they are not manipulating the top layer itself, but rather responding to the rendering behavior of being "on top of everything". For example, the presence of a ::backdrop pseudo relies on the element being rendered in the top layer; even if the element is pending removal, it has a ::backdrop as long as it’s being displayed on top of everything.

To add an element to the top layer, given an Element el:

Let doc be el’s node document.
If el is already contained in doc’s top layer:
- Assert: el is also in doc’s pending top layer removals. (Otherwise, this is a spec error.)
- Remove el from both doc’s top layer and pending top layer removals.
Append el to doc’s top layer.
At the UA !important cascade origin, add a rule targeting el containing an overlay: auto declaration.

To request an element to be removed from the top layer, given an Element el:

Let doc be el’s node document.
If el is not contained doc’s top layer, or el is already contained in doc’s pending top layer removals, return.
Remove the UA !important overlay: auto rule targeting el.
Append el to doc’s pending top layer removals.

To remove an element from the top layer immediately, given an Element el:

Let doc be el’s node document.
Remove el from doc’s top layer and pending top layer removals.
Remove the UA !important overlay: auto rule targeting el, if it exists.

Note: This algorithm is only intended to be used in special cases where removing something from the top layer immediately (bypassing things like an overlay transition) is necessary, such as a modal dialog that is removed from the document. Most of the time, requesting removal from the top layer is more appropriate.

To process top layer removals, given a Document doc:

For each element el in doc’s pending top layer removals: if el's computed value of overlay is none, or el is not rendered, remove from the top layer immediately el.

Note: This is intended to be called during the "Update the Rendering" step of HTML’s rendering algorithm. It is not intended to be called by other algorithms.

Note: The overlay check can be delayed arbitrarily long by author-level transitions; see § 3.4 Controlling the Top Layer: the overlay property for details.

3.4. Controlling the Top Layer: the overlay property

Name:	overlay
Value:	none \| auto
Initial:	none
Applies to:	all elements
Inherited:	no
Percentages:	n/a
Computed value:	as specified
Canonical order:	per grammar
Animation type:	see prose

When an element is in the top layer, the overlay property determines whether it is actually rendered in the top layer or not.

none

The element isn’t rendered in the top layer.

auto

The element is rendered in the top layer if it is in the top layer.

Rather than generating boxes as part of its normal position in the document, it generates boxes as a sibling of the root element, rendered "above" it.

Note: overlay is a somewhat unusual property, as it is only set by the user agent, and can’t be set by authors at all.

However, authors do have the ability to affect when overlay changes its value, by setting a transition on the property. This allows an author to align an animation with the transition, with the element moving in or out of the top layer only at the desired point in the animation. This allows, for example, an animation that causes an element to fade out of its normal position on the page, then fade in at its new top-layer position, or vice versa.

For animation, auto is interpolated as a discrete step where values of p such that 0 < p < 1 map to auto and other values of p map to the closer endpoint; if neither value is auto then discrete animation is used.

Note: This is similar to how visibility animates. With most easing functions, this will keep the element rendered in the top layer for the entire duration of the transition, whether it’s entering or leaving the top layer. step-start/step-end/linear() can be used to control when the value flips more precisely.

User agents must have the following rule in their UA stylesheet:

* { overlay: none !important; }

Note: This means that the overlay property cannot be set by authors or users—it is entirely controlled by the user agent (which sets elements to overlay: auto, via another UA-!important rule, when they’re in the top layer).

User agents may, at their discretion, remove a running transition on overlay. The conditions for this are intentionally undefined. (This is to prevent potential abuse scenarios where a transition: overlay 1e9s; or similar attempts to keep an element in the top layer permanently.)

4. Painting Order and Stacking Contexts

This chapter describes the painting order of CSS’s box tree.

When traversing the box tree, tree order is often used. For fragments, this refers to the logical order of the fragments, not the visual order. (This can be relevant, for example, when rending bidirectional text.)

Painting order is defined in terms of a "painter’s model", where elements are described as painting in a stack, with the bottom of the stack rendered "first", below items higher in the stack. The user is implied to exist above the top of the stack, looking down:

             |     |         |
             |          |    |   ⇦ 🧑‍🎨
             |          |        user
z-index:  canvas  -1    0    1

The stacking context background and most negative positioned stacking contexts are at the bottom of the stack, while the most positive positioned stacking contexts are at the top of the stack.

The canvas is transparent if contained within another, and given a UA-defined color if it is not. It is infinite in extent and contains the root element. Initially, the viewport is anchored with its top left corner at the canvas origin.

To paint a document, given a document doc and an infinite canvas canvas:

Paint a stacking context given doc’s root element and canvas.
For each element el in doc’s top layer:
1. Paint a stacking context given el's ::backdrop pseudo-element and canvas.
2. Paint a stacking context given el and canvas, treating el as a stacking context, with the initial containing block as its containing block.

To paint a stacking context given an element, pseudo-element, or box root, and an infinite canvas canvas:

If root is an element, paint a stacking context given root’s principal box and canvas, then return.
Assert: root is a box, and generates a stacking context.
If root is a root element’s principal box, paint root’s background over the entire canvas, with the origin of the background positioning area being the position on canvas that would be used if root’s background was being painted normally.
If root is a block-level box, paint a block’s decorations given root and canvas.
For each of root’s positioned descendants with negative (non-zero) z-index values, sort those descendants by z-index order (most negative first) then tree order, and paint a stacking context given each descendant and canvas.
For each of root’s in-flow, non-positioned, block-level descendants, in tree order, paint a block’s decorations given the descendant and canvas.
For each of root’s non-positioned floating descendants, in tree order, paint a stacking container given the descendant and canvas.
If root is an inline-level box

For each line box root is in, paint a box in a line box given root, the line box, and canvas.

Otherwise
First for root, then for all its in-flow, non-positioned, block-level descendant boxes, in tree order:
1. If the box is a replaced element, paint the replaced content into canvas, atomically.
2. Otherwise, for each line box of the box, paint a box in a line box given the box, the line box, and canvas.
3. If the UA uses in-band outlines, paint the outlines of the box into canvas.
For each of root’s positioned descendants with z-index: auto or z-index: 0, in tree order:

descendant has z-index: auto

Paint a stacking container given the descendant and canvas.

descendant has z-index: 0

Paint a stacking context given the descendant and canvas.
For each of root’s positioned descendants with positive (non-zero) z-index values, sort those descendants by z-index order (smallest first) then tree order, and paint a stacking context given each descendant and canvas.
If the UA uses out-of-band outlines, draw all of root’s outlines (those that it skipped drawing due to not using in-band outlines during the current invocation of this algorithm) into canvas.

To paint a block’s decorations given a block box root and a canvas canvas:

If root is not a table wrapper box:
1. Paint root’s background to canvas if it is not the root element’s principal box.
2. Paint root’s border to canvas.
If root is a table wrapper box:
1. Paint root’s background to canvas if it is not the root element’s principal box.
2. For each column group of root in tree order, paint the column group’s background to canvas.
3. For each column of root in tree order, paint the column’s background to canvas.
4. For each row group of root in tree order, paint the row group’s background to canvas.
5. For each row of root in tree order, paint the row’s background to canvas.
6. For each cell of root in tree order, paint the cell’s background to canvas.
7. Paint the borders of all of the table elements of root. If the borders are separated, do so in tree order; if connected, do so as specified in [css-tables-3].

To paint a box in a line box, given a box root, a line box line box, and a canvas canvas:

Paint the backgrounds of root’s fragments that are in line box into canvas.
Paint the borders of root’s fragments that are in line box into canvas.
If root is an inline box
For all root’s in-flow, non-positioned, inline-level children that generate fragments in line box, and all child text sequences that generate fragments in line box, in tree order:
If this child is a text sequence, then:
Paint any underlining affecting the text, in tree order of the elements applying the underlining (such that the deepest element’s underlining, if any, is painted topmost and the root element’s underlining, if any, is drawn bottommost) into canvas.

Paint any overlining affecting the text, in tree order of the elements applying the overlining (such that the deepest element’s overlining, if any, is painted topmost and the root element’s overlining, if any, is drawn bottommost) into canvas.

Paint the text into canvas.

Paint any line-through affecting the text, in tree order of the elements applying the line-through (such that the deepest element’s line-through, if any, is painted topmost and the root element’s line-through, if any, is drawn bottommost) into canvas.
If this child is a box:

Paint a box in a line box given the child, line box, and canvas.
If root is an inline-level block or table wrapper box

Paint a stacking container given root and canvas.

If root is an inline-level replaced element

Paint the replaced content into canvas, atomically.
If the UA uses in-band outlines, paint the outlines of root’s fragments that are in line box into canvas.

Note: Even though the visual order of inline box fragments can be rearranged within a line due to bidirectional reordering, the fragments are nevertheless painted in tree order.

To paint a stacking container, given a box root and a canvas canvas:

Paint a stacking context given root and canvas, treating root as if it created a new stacking context, but omitting any positioned descendants or descendants that actually create a stacking context (letting the parent stacking context paint them, instead).

UAs can draw outlines (from the outline property) either in-band (painted along each element, and thus potentially obscured/overlapping by following content) or out-of-band (all outlines painted at the end of the stacking context, so nothing in the stacking context can obscure them). It is recommended that UAs use out-of-band outlines, as making outlines easily visible is an important accessibility feature.

5. Changes

Significant changes since the 8 July 2025 First Public Working Draft:

None (markup and linking fixes only).

Privacy Considerations

No new privacy considerations have been reported on this specification.

Security Considerations

No new security considerations have been reported on this specification.

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.