1. Introduction
This is an early delta spec over [css-position-3].
2. 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.
-
Paint a stacking context given doc’s root element and canvas.
-
For each element el in doc’s top layer:
-
Paint a stacking context given el’s ::backdrop pseudo-element and canvas.
-
Paint a stacking context given el and canvas, treating el as a stacking context, with the initial containing block as its containing block.
-
-
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:
-
If the box is a replaced element, paint the replaced content into canvas, atomically.
-
Otherwise, for each line box of the box, paint a box in a line box given the box, the line box, and canvas.
-
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.
-
If root is not a table wrapper box:
-
Paint root’s background to canvas if it is not the root element’s principal box.
-
Paint root’s border to canvas.
-
-
If root is a table wrapper box:
-
Paint root’s background to canvas if it is not the root element’s principal box.
-
For each column group of root in tree order, paint the column group’s background to canvas.
-
For each column of root in tree order, paint the column’s background to canvas.
-
For each row group of root in tree order, paint the row group’s background to canvas.
-
For each row of root in tree order, paint the row’s background to canvas.
-
For each cell of root in tree order, paint the cell’s background to canvas.
-
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].
-
-
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.
-
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.
3. Scrollable Containing Block
When an element generates an absolute positioning containing block for its descendants, that containing block is generated from the element’s padding box edges. If that element is a scroll container, this corresponds to the dimensions of the scrollport, and does not shift as the scroll container is scrolled. In other words, it’s "outside of" the scrollable area.
Sometimes, however, you instead want a containing block based on the "inside" of the scroll container, sized according to the scrollable contents and shifting as the container is scrolled.
Whenever a scroll container generates an absolute positioning containing block, it addition to the normal containing block it generates, it also generates a scrollable containing block. This is sized to match the padding box edges of the scrollable area, and is treated as being "inside" the scrollable area, so it moves as the scroll container is scrolled.
Note: This is not quite the scrollable overflow rectangle; in particular, it doesn’t include the effects of transformed elements or absolutely positioned elements.
In containing block chains, the scrollable containing block generated by an element is considered a child of the element’s normal containing block, and a parent of any containing blocks generated by its descendants.
This also applies to the root scroller; a scrollable containing block that corresponds to the padding edges of the entire document is generated, and is considered a child of the initial containing block.
The scrollable containing block is not used by default, but certain CSS features (such as position-area) can specify that they use it instead of an element’s normal containing block.
4. 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.
4.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.
4.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 tree-abiding pseudo-element. It accepts all properties. It inherits from its originating 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 § 4.1 Top Layer Styling for additional details on how ::backdrop elements are rendered.
4.3. Top Layer Manipulation
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.
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.
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.
-
-
At the UA !important cascade origin, add a rule targeting el containing an overlay: auto declaration.
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.
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.
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 el from doc’s top layer and pending top layer removals.
Note: This is intended to be called during the "Update 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 § 4.4 Controlling the Top Layer: the overlay property for details.
4.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.
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.)