Overview.bs

<pre class='metadata'>
Title: CSS Positioned Layout Module Level 4
Status: ED
Work Status: Exploring
Shortname: css-position
Level: 4
Group: csswg
ED: https://drafts.csswg.org/css-position-4/
Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Tab Atkins Jr., Google, http://xanthir.com/contact/, w3cid 42199
Abstract: This module contains defines coordinate-based positioning and offsetting schemes of <a href="https://www.w3.org/TR/CSS/">CSS</a>: [=relative positioning=], [=sticky positioning=], [=absolute positioning=], and [=fixed positioning=].

	It also defines the painting/rendering model of CSS.
</pre>

<pre class=link-defaults>
spec:css-break-4; type:dfn; text:fragment
spec:dom; type:dfn; for:/; text:element
spec:css-position-4; type:dfn; for:Document; text:top layer
spec:infra; type:dfn; text:user agent
</pre>

<style>
/* Put nice boxes around each algorithm. */
[data-algorithm]:not(.heading) {
	padding: .5em;
	border: thin solid #ddd; border-radius: .5em;
	margin: .5em calc(-0.5em - 1px);
}
[data-algorithm]:not(.heading) > :first-child {
	margin-top: 0;
}
[data-algorithm]:not(.heading) > :last-child {
	margin-bottom: 0;
}
[data-algorithm] [data-algorithm] {
	margin: 1em 0;
}
</style>

Introduction {#intro}
=====================

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


<!--
 ██████  ████████    ███     ██████  ██    ██
██    ██    ██      ██ ██   ██    ██ ██   ██
██          ██     ██   ██  ██       ██  ██
 ██████     ██    ██     ██ ██       █████
      ██    ██    █████████ ██       ██  ██
██    ██    ██    ██     ██ ██    ██ ██   ██
 ██████     ██    ██     ██  ██████  ██    ██
-->

Painting Order and Stacking Contexts {#painting-order}
====================================

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:

	<pre class=ascii-art>
	             |     |         |
	             |          |    |   ⇦ ☻
	             |          |        user
	z-index:  canvas  -1    0    1
	</pre>

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.

<div algorithm>
	To <dfn export>paint a document</dfn>,
	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 [=Document/top layer=]:
		1. [=Paint a stacking context=]
			given |el|&apos;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=].
</div>

<div algorithm>
	To <dfn export>paint a stacking context</dfn>
	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.

	1. Assert: |root| is a [=box=],
		and generates a [=stacking context=].

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

	1. If |root| is a [=block-level box=],
		[=paint a block's decorations=]
		given |root| and |canvas|.

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

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

	1. For each of |root|'s non-positioned floating descendants,
		in tree order,
		[=paint a stacking container=]
		given the descendant and |canvas|.

	1.
		<dl class=switch>
			: 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|.
		</dl>

	1. For each of |root|'s positioned descendants
		with ''z-index: auto'' or ''z-index: 0'',
		in [=tree order=]:

		<dl class=switch>
			: 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|.
		</dl>

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

	1. 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|.
</div>

<div algorithm>
	To <dfn export>paint a block's decorations</dfn>
	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]].
</div>

<div algorithm>
	To <dfn export>paint a box in a line box</dfn>,
	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. <dl class=switch>
			: 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 [=CSS/text sequences=]
				that generate [=fragments=] in |line box|,
				in [=tree order=]:

				<dl class=switch>
					: 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 box|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.
		</dl>

	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 [[css-writing-modes-3#bidi-box-model|bidirectional reordering]],
	the fragments are nevertheless painted in tree order.
</div>

<div algorithm>
	To <dfn export>paint a stacking container</dfn>,
	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).
</div>

UAs can draw outlines (from the 'outline' property)
either <dfn export lt="in-band outline">in-band</dfn>
(painted along each element,
and thus potentially obscured/overlapping by following content)
or <dfn export lt="out-of-band outline">out-of-band</dfn>
(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.


Scrollable Containing Block {#scrollable-cb}
===========================

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 <dfn export>scrollable containing block</dfn>.
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 <em>quite</em> 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=].


<!--
████████  ███████  ████████
   ██    ██     ██ ██     ██
   ██    ██     ██ ██     ██
   ██    ██     ██ ████████
   ██    ██     ██ ██
   ██    ██     ██ ██
   ██     ███████  ██
-->

Top Layer {#top-layer}
=========

{{Document}}s have a <dfn export for=Document>top layer</dfn>,
an [=ordered set=] containing [=elements=] from the document.
Elements in the [=Document/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.
[=Document/Top layer=] elements are rendered in the order they appear in the [=Document/top layer=];
the last element in the [=Document/top layer=] is rendered on top of everything else.

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

The <dfn export>top layer root</dfn> of an element
is its nearest ancestor element
that is in the [=Document/top layer=],
or none otherwise
(in which case it's painted as part of the document as normal).

Two elements are <dfn export>in the same top layer</dfn>
if they have the same [=top layer root=]
(including if both are none).
An element A is <dfn export>in a higher top layer</dfn>
than an element B
if A has a [=top layer root=],
and either B has a [=top layer root=] earlier in the [=Document/top layer=] than A's,
or B doesn't have a [=top layer root=] at all.

Note: The [=Document/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 [=Document/top layer=] interacts with the 'overlay' property
in a somewhat unusual way.
See 'overlay' for details.

{{Document}}s also have a <dfn export>pending top layer removals</dfn> [=ordered set=],
containing elements that are pending removal.
(See the algorithms, below, for details on how this is used.)

The [=Document/top layer=]
(and the [=pending top layer removals=])
should not be interacted with directly
by specification algorithms.
(Individual features using the [=Document/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.

Top Layer Styling {#top-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 ''position/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 ''display/contents'',
	it computes to ''display/block''.

* If its specified 'position' property
	is not ''position/absolute'' or ''position/fixed'',
	it computes to ''position/absolute''.

* Unless overridden by another specification,
	its static position for left, right, and top is zero.


The ''::backdrop'' Pseudo-Element {#backdrop}
---------------------------------

Each element [=rendered in the top layer=] has a <dfn selector>::backdrop</dfn> pseudo-element,
for which it is the [=originating element=].

When its computed 'content' value is not ''content/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 [=Document/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:

<pre highlight=css>
::backdrop {
	position: fixed;
	inset: 0;
}
</pre>

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 [[#top-styling]] for additional details
on how ''::backdrop'' elements are rendered.


Top Layer Manipulation {#top-manip}
----------------------

<div algorithm>
	An element |el| is <dfn export>in the top layer</dfn>
	if |el| is [=list/contained=] in its [=Node/node document's=] [=Document/top layer=]
	but <em>not</em> [=list/contained=] in its [=Node/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 <em>between</em> rendering updates
	or <em>across</em> them.
</div>

<div algorithm>
	An element |el| is <dfn export lt="render in the top layer">rendered in the top layer</dfn>
	if |el| is [=list/contained=] in its [=Node/node document's=] [=Document/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 top layer removals|pending removal=],
	it has a ''::backdrop'' as long as it's being displayed on top of everything.
</div>

<div algorithm>
	To <dfn export lt="add an element to the top layer | add to the top layer">add an element to the top layer</dfn>,
	given an {{Element}} |el|:

	1. Let |doc| be |el|'s [=Node/node document=].

	2. If |el| is already [=list/contained=] in |doc|'s [=Document/top layer=]:
		* Assert: |el| is also in |doc|'s [=pending top layer removals=].
			(Otherwise, this is a spec error.)
		* [=set/Remove=] |el| from both |doc|'s [=Document/top layer=]
			and [=pending top layer removals=].

	3. [=set/Append=] |el| to |doc|'s [=Document/top layer=].

	4. At the UA !important [=cascade origin=],
		add a rule targeting |el|
		containing an ''overlay: auto'' declaration.
</div>

<div algorithm>
	To <dfn export lt="request an element to be removed from the top layer | request removal from the top layer">request an element to be removed from the top layer</dfn>,
	given an {{Element}} |el|:

	1. Let |doc| be |el|'s [=Node/node document=].

	2. If |el| is not [=list/contained=] |doc|'s [=Document/top layer=],
		or |el| <em>is</em> already [=list/contained=]
		in |doc|'s [=pending top layer removals=],
		return.

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

	4. [=set/Append=] |el| to |doc|'s [=pending top layer removals=].
</div>

<div algorithm>
	To <dfn export lt="remove an element from the top layer immediately | remove from the top layer immediately">remove an element from the top layer immediately</dfn>,
	given an {{Element}} |el|:

	1. Let |doc| be |el|'s [=Node/node document=].

	2. [=set/Remove=] |el| from |doc|'s [=Document/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.
</div>

<div algorithm>
	To <dfn export>process top layer removals</dfn>,
	given a {{Document}} |doc|:

	1. For each element |el| in |doc|'s [=pending top layer removals=]:
		if |el|&apos;s computed value of 'overlay' is ''none'',
		or |el| is [=not rendered=],
		[=set/remove=] |el| from |doc|'s [=Document/top layer=]
		and [=pending top layer removals=].

	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 [[#overlay]] for details.
</div>


<!--
 ███████  ██     ██ ████████ ████████  ██          ███    ██    ██
██     ██ ██     ██ ██       ██     ██ ██         ██ ██    ██  ██
██     ██ ██     ██ ██       ██     ██ ██        ██   ██    ████
██     ██ ██     ██ ██████   ████████  ██       ██     ██    ██
██     ██  ██   ██  ██       ██   ██   ██       █████████    ██
██     ██   ██ ██   ██       ██    ██  ██       ██     ██    ██
 ███████     ███    ████████ ██     ██ ████████ ██     ██    ██
-->

Controlling the Top Layer: the 'overlay' property {#overlay}
-------------------------------------------------

<pre class=propdef>
Name: overlay
Value: none | auto
Initial: none
Inherited: no
Animation Type: see prose
</pre>

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

<dl dfn-type=value dfn-for=overlay>
	: <dfn>none</dfn>
	:: The element isn't [=rendered in the top layer=].

	: <dfn>auto</dfn>
	:: 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.
</dl>

<div class=note id=overlay-guidance>
	Note: 'overlay' is a somewhat unusual property,
	as it is <em>only</em> set by the user agent,
	and can't be set by authors <em>at all</em>.

	However, authors <em>do</em> have the ability to affect
	<em>when</em> '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.
</div>

For animation,
''overlay/auto'' is [=interpolated=] as a discrete step
where values of p such that <code>0 < p < 1</code>
map to ''overlay/auto''
and other values of p map to the closer endpoint;
if neither value is ''overlay/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:

<pre highlight=css>
* { overlay: none !important; }
</pre>

Note: This means that the 'overlay' property <em>cannot be set by authors or users</em>--
it is entirely controlled by the user agent
(which sets elements to ''overlay: auto'',
via another UA-!important rule,
when they're in the [=Document/top layer=]).

User agents <em>may</em>, at their discretion,
remove a running [=transition=] on 'overlay'.
The conditions for this are intentionally undefined.
<span class=note>(This is to prevent potential abuse scenarios
where a ''transition: overlay 1e9s;'' or similar
attempts to keep an element in the [=Document/top layer=] permanently.)</span>