CSS Positioned Layout Module Level 4

Editor’s Draft,

More details about this document
This version:
https://drafts.csswg.org/css-position-4/
Issue Tracking:
CSSWG Issues Repository
Editors:
Elika J. Etemad / fantasai (Apple)
Tab Atkins Jr. (Google)
Suggest an Edit for this Spec:
GitHub Editor

Abstract

This module contains defines coordinate-based positioning and offsetting schemes of CSS: relative positioning, sticky positioning, absolute positioning, and fixed positioning.

It also defines the painting/rendering model of CSS.

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, etc.

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

Please send feedback by filing issues in GitHub (preferred), including the spec code “css-position” in the title, like this: “[css-position] …summary of comment…”. All issues and comments are archived. Alternately, feedback can be sent to the (archived) public mailing list www-style@w3.org.

This document is governed by the 03 November 2023 W3C Process Document.

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.

To paint a document, given a document doc and an infinite canvas canvas:
  1. Paint a stacking context given doc’s root element and canvas.

  2. 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:
  1. If root is an element, paint a stacking context given root’s principal box and canvas, then return.

  2. Assert: root is a box, and generates a stacking context.

  3. 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.

  4. If root is a block-level box, paint a block’s decorations given root and canvas.

  5. 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.

  6. 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.

  7. For each of root’s non-positioned floating descendants, in tree order, paint a stacking container given the descendant and canvas.

  8. 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.

  9. 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.

  10. 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.

  11. 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:
  1. 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.

  2. 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:
  1. Paint the backgrounds of root’s fragments that are in line box into canvas.

  2. Paint the borders of root’s fragments that are in line box into canvas.

  3. 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:
    1. 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.

    2. 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.

    3. Paint the text into canvas.

    4. 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.

  4. 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:
  1. 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. 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.

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:

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 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 § 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:
  1. Let doc be el’s node document.

  2. If el is already contained in doc’s top layer:

  3. Append el to doc’s top layer.

  4. 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:
  1. Let doc be el’s node document.

  2. If el is not contained doc’s top layer, or el is already contained in doc’s pending top layer removals, return.

  3. Remove the UA !important overlay: auto rule targeting el.

  4. Append el to doc’s pending top layer removals.

To remove an element from the top layer immediately, given an Element el:
  1. Let doc be el’s node document.

  2. Remove el from doc’s top layer and pending top layer removals.

  3. 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:
  1. 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 § 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.)

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Tests

Tests relating to the content of this specification may be documented in “Tests” blocks like this one. Any such block is non-normative.


Conformance classes

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Partial implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-BREAK-4]
Rossen Atanassov; Elika Etemad. CSS Fragmentation Module Level 4. URL: https://drafts.csswg.org/css-break-4/
[CSS-CASCADE-6]
Elika Etemad; Miriam Suzanne; Tab Atkins Jr.. CSS Cascading and Inheritance Level 6. URL: https://drafts.csswg.org/css-cascade-6/
[CSS-CONTENT-3]
Elika Etemad; Dave Cramer. CSS Generated Content Module Level 3. URL: https://drafts.csswg.org/css-content-3/
[CSS-DISPLAY-4]
CSS Display Module Level 4. Editor's Draft. URL: https://drafts.csswg.org/css-display-4/
[CSS-POSITION-3]
Elika Etemad; Tab Atkins Jr.. CSS Positioned Layout Module Level 3. URL: https://drafts.csswg.org/css-position-3/
[CSS-PSEUDO-4]
Daniel Glazman; Elika Etemad; Alan Stearns. CSS Pseudo-Elements Module Level 4. URL: https://drafts.csswg.org/css-pseudo-4/
[CSS-TABLES-3]
François Remy; Greg Whitworth; David Baron. CSS Table Module Level 3. URL: https://drafts.csswg.org/css-tables-3/
[CSS-UI-4]
Florian Rivoal. CSS Basic User Interface Module Level 4. URL: https://drafts.csswg.org/css-ui-4/
[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. URL: https://drafts.csswg.org/css-values-4/
[CSS21]
Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. URL: https://drafts.csswg.org/css2/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[SELECTORS-4]
Elika Etemad; Tab Atkins Jr.. Selectors Level 4. URL: https://drafts.csswg.org/selectors/

Informative References

[CSS-COLOR-4]
Chris Lilley; Tab Atkins Jr.; Lea Verou. CSS Color Module Level 4. URL: https://drafts.csswg.org/css-color-4/
[CSS-EASING-2]
CSS Easing Functions Level 2. Editor's Draft. URL: https://drafts.csswg.org/css-easing-2/
[CSS-MASKING-1]
Dirk Schulze; Brian Birtles; Tab Atkins Jr.. CSS Masking Module Level 1. URL: https://drafts.fxtf.org/css-masking-1/
[CSS-OVERFLOW-3]
Elika Etemad; Florian Rivoal. CSS Overflow Module Level 3. URL: https://drafts.csswg.org/css-overflow-3/
[CSS-TRANSITIONS-1]
David Baron; et al. CSS Transitions. URL: https://drafts.csswg.org/css-transitions/
[CSS-WRITING-MODES-3]
Elika Etemad; Koji Ishii. CSS Writing Modes Level 3. URL: https://drafts.csswg.org/css-writing-modes-3/
[FULLSCREEN]
Philip Jägenstedt. Fullscreen API Standard. Living Standard. URL: https://fullscreen.spec.whatwg.org/

Property Index

Name Value Initial Applies to Inh. %ages Anim­ation type Canonical order Com­puted value
overlay none | auto none all elements no n/a (see prose) per grammar as specified
MDN

::backdrop

In all current engines.

Firefox47+Safari15.4+Chrome37+
Opera?Edge79+
Edge (Legacy)NoneIENone
Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?