<pre class='metadata'>

Title: CSS Anchor Positioning

Shortname: css-anchor-position

Level: 1

Status: ED

Prepare for TR: no

Group: csswg

Work Status: exploring

ED: https://drafts.csswg.org/css-anchor-position-1/

TR: https://www.w3.org/TR/css-anchor-position-1/

Editor: Tab Atkins-Bittner, Google, http://xanthir.com/contact/, w3cid 42199

Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400

Former Editor: Jhey Tompkins, Google, https://twitter.com/jh3yy, w3cid 137616

Editor: Ian Kilpatrick, Google, w3cid 73001

Abstract: This specification defines 'anchor positioning', where a positioned element can size and position itself relative to one or more "anchor elements" elsewhere on the page.

Ignored Terms: cssText, transitions

</pre>

<pre class=link-defaults>

spec:css-backgrounds-3; type:property; text:border-color

spec:css-break-4; type:dfn; text:fragment

spec:css-display-3; type:dfn; text:element

spec:css-position-3;

type:dfn; text:inset-modified containing block

type:property; text:inset-inline-start

spec:css-cascade-5; type:dfn; text:property

spec:dom; type:dfn; text:shadow tree

</pre>

<pre class=anchors>

spec:aria-1.3; type: element-attr; text: role; for: html-global; url: https://w3c.github.io/aria/#host_general_role

</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}

=====================

CSS [=absolute positioning=] allows authors

to place elements anywhere on the page,

without regard to the layout of other elements

besides their containing block.

This flexibility can be very useful,

but also very limiting--

often you want to position relative to <em>some</em> other element.

<dfn export>Anchor positioning</dfn>

(via the <dfn export>anchor functions</dfn> ''anchor()'' and ''anchor-size()'')

allows authors to achieve this,

"anchoring" an [=absolutely-positioned=] element

to one or more other elements on the page,

while also allowing them to try several possible positions

to find the "best" one that avoids overlap/overflow.

For example, an author might want to position a tooltip

centered and above the targeted element,

unless that would place the tooltip offscreen,

in which case it should be below the targeted element.

This can be done with the following CSS:

<div class=example>

<pre class=lang-css>

.anchor {

anchor-name: --tooltip;

}

.tooltip {

/* Fixpos means we don't need to worry about

containing block relationships;

the tooltip can live anywhere in the DOM. */

position: fixed;

/* All the anchoring behavior will default to

referring to the --tooltip anchor. */

position-anchor: --tooltip;

/* Align the tooltip's bottom to the top of the anchor;

this also defaults to horizontally center-aligning

the tooltip and the anchor (in horizontal writing modes). */

position-area: block-start;

/* Automatically swap if this overflows the window

so the tooltip's top aligns to the anchor's bottom

instead. */

position-try: flip-block;

/* Prevent getting too wide */

max-inline-size: 20em;

}

</pre>

</div>

Determining the Anchor {#determining}

======================

<!-- Big Text: a-name

███▌ █ █▌ ███▌ █ █ █████▌

▐█ ▐█ █▌ █▌ ▐█ ▐█ ██ ██ █▌

█▌ █▌ ██▌ █▌ █▌ █▌ █▌█ █▐█ █▌

█▌ █▌ ████▌ █▌▐█ █▌ █▌ █▌ █▌ █ ▐█ ████

█████▌ █▌ ██▌ █████▌ █▌ ▐█ █▌

█▌ █▌ █▌ █▌ █▌ █▌ █▌ ▐█ █▌

█▌ █▌ █▌ ▐▌ █▌ █▌ █▌ ▐█ █████▌

-->

Creating an Anchor: the 'anchor-name' property {#name}

----------------------------------------------

<pre class=propdef>

Name: anchor-name

Value: none | <<dashed-ident>>#

Initial: none

Inherited: no

Applies to: all elements that generate a [=principal box=]

Animation Type: discrete

</pre>

The 'anchor-name' property declares

that an element is an <dfn local-lt=anchor>anchor element</dfn>,

and gives it a list of <dfn lt="anchor name">anchor names</dfn> to be targeted by.

Values are defined as follows:

<dl dfn-type=value dfn-for=anchor-name>

: <dfn>none</dfn>

:: The property has no effect.

: <dfn><<dashed-ident>>#</dfn>

:: If the element generates a [=principal box=],

the element is an [=anchor element=],

with a list of [=anchor names=] as specified.

Each [=anchor name=] is a [=tree-scoped name=].

Otherwise, the property has no effect.

</dl>

[=Anchor names=] do not need to be unique.

Not all elements are capable of being [=anchor elements=]

for a given positioned element,

so a name can be reused in multiple places

if the usages are scoped appropriately.

Note: If multiple elements share an [=anchor name=]

and are all visible to a given positioned element,

the [=target anchor element=] will be the last one in DOM order.

'anchor-scope' can be used to limit what names are visible to a given element.

[=Anchor names=] are <em>not</em> scoped by [=containment=] by default;

even if an element has [=style containment|style=] or [=layout containment=]

(or any similar sort of containment),

the [=anchor names=] of its descendants are visible to elements elsewhere in the page.

Note: While an element is in the [=skipped contents=] of another element

(due to ''content-visibility: hidden'', for instance),

it's not an [=acceptable anchor element=],

effectively acting as if it had no names.

### Implicit Anchor Elements ### {#implicit}

Some specifications can define that,

in certain circumstances,

a particular element is an <dfn>implicit anchor element</dfn>

for a given positioned element.

<p class=example>

TODO: Fill in an example using the "anchor" attribute

(once that finally lands in the HTML spec),

which sets the implicit anchor element.

[=Implicit anchor elements=] can be referenced

with the ''implicit'' keyword,

rather than referring to some 'anchor-name' value.

[=Pseudo-elements=]

have the same [=implicit anchor element=]

as their [=originating element=],

unless otherwise specified.

Note: Without this, these [=pseudo-elements=], which are often inaccessible

by other specifications, cannot be positioned with [=implicit anchor elements=].

<!-- Big Text: a-scope

███▌ ███▌ ███▌ ███▌ ████▌ █████▌

▐█ ▐█ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌

█▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌

█▌ █▌ ████▌ ███▌ █▌ █▌ █▌ ████▌ ████

█████▌ █▌ █▌ █▌ █▌ █▌ █▌

█▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌

█▌ █▌ ███▌ ███▌ ███▌ █▌ █████▌

-->

<h3 id='anchor-scope'>

Scoping Anchor Names: the 'anchor-scope' property</h3>

<pre class=propdef>

Name: anchor-scope

Value: none | all | <<dashed-ident>>#

Initial: none

Applies to: all elements

Inherited: no

Animation type: discrete

Computed value: as specified

</pre>

This property scopes the specified [=anchor names=],

and lookups for these [=anchor names=],

to this element's subtree.

See [[#determining]].

Values have the following meanings:

<dl dfn-for="anchor-scope" dfn-type=value>

<dt><dfn>none</dfn>

<dd>

No changes in [=anchor name=] scope.

<dt><dfn>all</dfn>

<dd>

Specifies that all [=anchor names=] defined by this element or its descendants--

whose scope is not already limited by a descendant using 'anchor-scope'--

to be in scope only for this element's descendants;

and limits descendants to only match [=anchor names=]

to [=anchor elements=] within this subtree.

<dt><dfn><<dashed-ident>></dfn>

<dd>

Specifies that a matching [=anchor name=] defined by this element or its descendants--

whose scope is not already limited by a descendant using 'anchor-scope'--

to be in scope only for this element's descendants;

and limits descendants to only match these [=anchor names=]

to [=anchor elements=] within this subtree.

</dl>

This property has no effect on [=implicit anchor elements=].

<div class=example>

When a design pattern is re-used,

'anchor-scope' can prevent naming clashes across identical components.

For example, if a list contains positioned elements in each list item,

which want to position themselves relative to the list item they're in,

<pre class=lang-css>

li {

anchor-name: --list-item;

anchor-scope: --list-item;

}

li .positioned {

position: absolute;

position-anchor: --list-item;

position-area: inline-start;

}

</pre>

Without 'anchor-scope',

all of the <{li}> elements would be visible

to all of the positioned elements,

and so they'd all positioned themselves relative to the <em>final</em> <{li}>,

stacking up on top of each other.

</div>

<!-- Big Text: lookup

█▌ ███▌ ███▌ █▌ █▌ █▌ █▌ ████▌

█▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌

█▌ █▌ █▌ █▌ █▌ █▌█▌ █▌ █▌ █▌ █▌

█▌ █▌ █▌ █▌ █▌ ██ █▌ █▌ ████▌

█▌ █▌ █▌ █▌ █▌ █▌█▌ █▌ █▌ █▌

█▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌

█████ ███▌ ███▌ █▌ █▌ ███▌ █▌

-->

Finding an Anchor {#target}

-----------------

Several things in this specification

find a [=target anchor element=],

given an <dfn>anchor specifier</dfn>,

which is either a <<dashed-ident>>

(and a [=tree-scoped reference=])

that should match an 'anchor-name' value elsewhere on the page,

or the keyword ''implicit'',

or nothing (a missing specifier).

Note: The general rule captured by these conditions

is that an element can only be an anchor

if it's fully laid out

before the positioned element that wants to reference it

is laid out.

CSS's layout rules provide some useful guarantees about this,

depending on the anchor and positioned element's relationship

with each other and their containing blocks.

The list of conditions below

exactly rephrases the stacking context rules

into just what's relevant for this purpose,

ensuring there is no possibly circularity

in anchor positioning.

<div algorithm>

To determine the <dfn>target [=anchor element=]</dfn>

given a querying element |query el|

and an optional [=anchor specifier=] |anchor spec|:

1. If |anchor spec| was not passed,

return the [=target anchor element=]

for |query el|

given the |query el|'s [=default anchor specifier=].

2. If |anchor spec| is ''implicit'':

1. If the Popover API defines an [=implicit anchor element=] for |query el|

which is an [=acceptable anchor element=] for |query el|,

return that element.

2. Otherwise, return nothing.

Note: Future APIs might also define implicit anchor elements.

When they do, they'll be explicitly handled in this algorithm,

to ensure coordination.

3. Otherwise, |anchor spec| is a <<dashed-ident>>.

Return the last element |el| in tree order

that satisfies the following conditions:

* |el| is an [=anchor element=] with an [=anchor name=] of |anchor spec|.

* |el|'s [=anchor name=] and |anchor spec| are both associated with the same [=tree=] [=tree/root=].

Note: The [=anchor name=] is a [=tree-scoped name=],

while |anchor spec| is a [=tree-scoped reference=].

* |el| is an [=acceptable anchor element=] for |query el|.

If no element satisfies these conditions,

return nothing.

Note: 'anchor-scope' can restrict the visibility

of certain [=anchor names=],

which can affect what elements can be [=anchor elements=]

for a given lookup.

Note: An 'anchor-name' defined by styles in one [=shadow tree=]

won't be seen by [=anchor functions=] in styles in a different [=shadow tree=],

preserving encapsulation.

However, <em>elements</em> in different [=shadow trees=]

can still anchor to each other,

so long as both the 'anchor-name' and [=anchor function=]

come from styles in the same tree,

such as by using ''::part()'' to style an element inside a shadow.

([=Implicit anchor elements=] also aren't intrinsically limited to a single tree,

but the details of that will depend on the API assigning them.)

</div>

<div algorithm="acceptable anchor element">

An element |el| is a <dfn export>acceptable anchor element</dfn>

for an [=absolutely positioned=] element |query el|

if all of the following are true:

* Either |el| is a descendant of |query el|'s [=containing block=],

or |query el|'s [=containing block=] is the [=initial containing block=].

* If |el| has the same [=containing block=] as |query el|,

then either |el| is not [=absolutely positioned=],

or |el| precedes |query el| in the tree order.

* If |el| has a different [=containing block=] from |query el|,

then the last [=containing block=] in |el|'s [=containing block chain=]

before reaching |query el|'s [=containing block=]

is either not [=absolutely positioned=]

or precedes |query el| in the tree order.

* |el| is either an [=element=]

or a [=part-like pseudo-element=].

* If |el| is in the [=skipped contents=] of another element,

then |query el| is in the [=skipped contents=] of that same element.

Note: In other words, |query el| can anchor to |el|

if they're both in the same skipped "leaf",

but it can't anchor "across" leafs.

* |el| is in scope for |query el|,

per the effects of 'anchor-scope' on |query el|

or its ancestors.

</div>

<!-- Big Text: default

████▌ █████▌ █████▌ ███▌ █▌ █▌ █▌ █████▌

█▌ █▌ █▌ █▌ ▐█ ▐█ █▌ █▌ █▌ █▌

█▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌

█▌ █▌ ████ ████ █▌ █▌ █▌ █▌ █▌ █▌

█▌ █▌ █▌ █▌ █████▌ █▌ █▌ █▌ █▌

█▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌

████▌ █████▌ █▌ █▌ █▌ ███▌ █████ █▌

-->

<h3 id=position-anchor>

Default Anchors: the 'position-anchor' property</h3>

<pre class=propdef>

Name: position-anchor

Value: auto | <<anchor-element>>

Initial: auto

Applies to: [=absolutely positioned=] elements

Inherited: no

Animation type: discrete

</pre>

The 'position-anchor' property defines the <dfn>default anchor specifier</dfn>

for all [=anchor functions=] on the element,

allowing multiple elements to use the same set of [=anchor functions=]

(and [=position options lists=]!)

while changing which [=anchor element=] each is referring to.

'position-anchor' is a [=reset-only sub-property=] of 'position'.

The [=target anchor element=] selected by the [=default anchor specifier=]

(if one exists)

is the element's <dfn>default anchor element</dfn>.

Its values are identical to the <<anchor-element>> term

in ''anchor()'' and ''anchor-size()'',

except that the ''position-anchor/auto'' value

is equivalent to omitting the <<anchor-element>> in ''anchor()''

(referring to the [=implicit anchor element=], if one exists).

<div class=example>

For example, in the following code

both ''.foo'' and ''.bar'' elements

can use the same positioning properties,

just changing the anchor element they're referring to:

<pre highlight=css>

.anchored {

position: absolute;

top: calc(.5em + anchor(outside));

/* Since no anchor name was specified,

this automatically refers to the

default anchor element. */

}

.foo.anchored {

position-anchor: --foo;

}

.bar.anchored {

position-anchor: --bar;

}

</pre>

</div>

<h3 id=anchor-relevance>

Anchor Relevance</h3>

When determining whether an element |el| is [=relevant to the user=],

if a descendant of |el| is a [=target anchor element=]

for a positioned element

(which is not [=skipped contents|skipped=]

and whose containing block is not |el|

or a descendant of |el|),

then |el| must be considered [=relevant to the user=].

Note: This means that, for example,

an anchor in a ''content-visibility: auto'' subtree

will prevent its subtree from [=skipping its contents=]

as long as the positioned element relying on it

is also not [=skipped contents|skipped=].

(Unless the anchor and the positioned element

are both under the same ''content-visibility: auto'' element;

they can't cyclicly keep each other visible.)

Anchor-Based Positioning {#positioning}

========================

An [=absolutely-positioned=] element

can position itself relative to one or more [=anchor elements=] on the page.

The 'position-area' property offers a convenient grid-based concept

for positioning relative to the [=default anchor element=];

for more complex positioning or positioning relative to multiple elements,

the ''anchor()'' function can be used in the [=inset properties=]

to explicitly refer to edges of an [=anchor element=].

<!-- Big Text: position-area

████ ███ █████ █████ █████ █████ ███ █ █ ███ ████ █████ ███

█ █ █ █ █ █ █ █ █ █ ██ █ █ █ █ █ █ █ █

████ █ █ █████ █ █ █ █ █ █ █ █ ███ █████ ████ ████ █████

█ █ █ █ █ █ █ █ █ █ ██ █ █ █ █ █ █ █

█ ███ █████ █████ █ █████ ███ █ █ █ █ █ █ █████ █ █

-->

The 'position-area' Property {#position-area}

---------------------------------------

<pre class=propdef>

Name: position-area

Value: none | <<position-area>>

Initial: none

Inherited: no

Applies to: positioned elements with a [=default anchor element=]

Animation type: TBD

</pre>

Most common use-cases of anchor positioning

only need to worry about

the edges of the positioned element's [=containing block=],

and the edges of the [=default anchor element=].

These lines can be thought of as defining a 3x3 grid;

'position-area' lets you easily set up the positioned element's [=inset properties=]

by specifying what area of this [=position-area grid=] you want the positioned element to be in.

Its syntax is:

<pre class=prod>

<dfn>&lt;position-area></dfn> = [

[ left | center | right | span-left | span-right

| x-start | x-end | span-x-start | span-x-end

| x-self-start | x-self-end | span-x-self-start | span-x-self-end

| span-all ]

||

[ top | center | bottom | span-top | span-bottom

| y-start | y-end | span-y-start | span-y-end

| y-self-start | y-self-end | span-y-self-start | span-y-self-end

| span-all ]

|

[ block-start | center | block-end | span-block-start | span-block-end | span-all ]

||

[ inline-start | center | inline-end | span-inline-start | span-inline-end

| span-all ]

|

[ self-block-start | center | self-block-end | span-self-block-start

| span-self-block-end | span-all ]

||

[ self-inline-start | center | self-inline-end | span-self-inline-start

| span-self-inline-end | span-all ]

|

[ start | center | end | span-start | span-end | span-all ]{1,2}

|

[ self-start | center | self-end | span-self-start | span-self-end | span-all ]{1,2}

]

</pre>

<dl dfn-for=position-area dfn-type=value>

: <dfn>none</dfn>

:: The property has no effect.

: <dfn><<position-area>></dfn>

::

If the element does not have a [=default anchor element=],

or is not an [=absolutely-positioned=] element,

this value has no effect.

Otherwise, it has the following effects:

* The property selects a region of the [=position-area grid=],

and makes that the element's [=containing block=].

See [[#resolving-spans]] for details.

Note: This means that the [=inset properties=] specify offsets from the position-area,

and some property values,

like ''max-height: 100%'',

will be relative to the position-area as well.

* The ''align-self/normal'' value for the [=self-alignment properties=]

behaves as either ''align-self/start'', ''align-self/end'',

or ''align-self/anchor-center'',

depending on the positioning of the region,

to give a good default alignment for the positioned element.

Again, see [[#resolving-spans]] for details.

* Any ''top/auto'' [=inset properties=] resolve to ''0''.

* The element is not considered to be in a [=legacy alignment mode=]

in either axis.

</dl>

<div class=note>

If the element overflows its 'position-area' (and 'inset') -modified [=containing block=],

but would still fit within its [=original containing block=],

by default it will "shift" to stay within its [=original containing block=],

even if that violates its normal alignment.

See [[css-align-3#overflow-values]] for details.

This behavior makes it more likely

that positioned elements remain visible

and within their intended bounds,

even when their [=containing block=]

ends up smaller than anticipated.

For example, an ''position-area: bottom span-right'' value

lets the positioned element stretch

from its anchors left edge

to its containing block's right edge,

and left-aligns it in that space by default.

But if the positioned element is larger than that space

(such as if the anchor is very close to the right edge of the screen),

it will shift leftwards to stay visible.

</div>

<h4 id=resolving-spans>

Resolving <<position-area>>s</h4>

The <dfn export>position-area grid</dfn> is a 3x3 grid,

composed of four grid lines in each axis.

In order:

* the start edge of the element's pre-modification [=containing block=],

or the ''anchor-start()'' edge of the [=default anchor element=]

if that is more [=start=]-ward

* the ''anchor(start)'' edge of the [=default anchor element=]

* the ''anchor(end)'' edge of the [=default anchor element=]

* the end edge of the element's pre-modification [=containing block=],

or the ''anchor-start()'' edge fo the [=default anchor element=]

if that is more [=end=]-ward.

An <<position-area>> selects a region of this grid

by specifying the rows and columns the region occupies,

with each of the two keywords specifying one of them:

<dl dfn-type=value dfn-for="position-area, <position-area>">

: <dfn>start</dfn>, <dfn>end</dfn>, <dfn>self-start</dfn>, <dfn>self-end</dfn>

: <dfn>top</dfn>, <dfn>bottom</dfn>, <dfn>left</dfn>, <dfn>right</dfn>

: <dfn>y-start</dfn>, <dfn>y-end</dfn>, <dfn>y-self-start</dfn>, <dfn>y-self-end</dfn>

: <dfn>x-start</dfn>, <dfn>x-end</dfn>, <dfn>x-self-start</dfn>, <dfn>x-self-end</dfn>

: <dfn>block-start</dfn>, <dfn>block-end</dfn>, <dfn>block-self-start</dfn>, <dfn>block-self-end</dfn>

: <dfn>inline-start</dfn>, <dfn>inline-end</dfn>, <dfn>inline-self-start</dfn>, <dfn>inline-self-end</dfn>

: <dfn>center</dfn>

:: The single corresponding row or column,

depending on which axis this keyword is specifying.

Like in ''anchor()'',

the plain logical keywords

(''position-area/start'', ''position-area/end'', etc)

refer to the writing mode of the element's [=containing block=].

The ''position-area/x-start''/etc determine their direction in the same way,

but in the specified physical axis.

The "self" logical keywords

(''position-area/self-start'', ''position-area/x-self-end'', etc)

are identical,

but refer to the element's own writing mode.

: <dfn>span-start</dfn>, <dfn>span-end</dfn>

: <dfn>span-top</dfn>, <dfn>span-bottom</dfn>

: <dfn>span-y-start</dfn>, <dfn>span-y-end</dfn>

: <dfn>span-x-start</dfn>, <dfn>span-x-end</dfn>

: <dfn>span-block-start</dfn>, <dfn>span-block-end</dfn>

: <dfn>span-inline-start</dfn>, <dfn>span-inline-end</dfn>

:: Two rows or columns,

depending on which axis this keyword is specifying:

the center row/column,

and the row/column corresponding to the other half of the keyword

as per the single-track keywords.

(For example, ''span-top'' spans the first two rows--

the center row and the top row.)

: <dfn>span-all</dfn>

:: All three rows or columns,

depending on which axis this keyword is specifying.

</dl>

Some keywords are ambiguous about what axis they refer to:

''position-area/center'', ''position-area/span-all'',

and the ''position-area/start''/etc keywords that don't specify the block or inline axis explicitly.

If the other keyword is unambiguous about its axis,

then the ambiguous keyword is referring to the opposite axis.

(For example, in ''block-start center'',

the ''position-area/center'' keyword is referring to the inline axis.)

If both keywords are ambiguous, however,

then the first refers to the block axis of the element's [=containing block=],

and the second to the inline axis.

(For example, ''span-all start'' is equivalent to ''span-all inline-start''.)

If only a single keyword is given,

it behaves as if the second keyword is ''position-area/span-all''

if the given keyword is unambigous about its axis;

otherwise, it behaves as if the given keyword was repeated.

(For example, ''position-area/top'' is equivalent to ''top span-all'',

but ''position-area/center'' is equivalent to ''center center''.)

<hr>

The <<position-area>> also implies a default [=self-alignment=],

which will be used if the [=self-alignment property=] on the element

is ''align-self/normal'':

* If the only the center region in an axis is selected,

or all three regions are selected,

the default alignment in that axis is ''align-self/anchor-center''.

* Otherwise, the default alignment in that axis

is toward the non-specified side region:

if it's specifying the "start" region of its axis,

the default alignment in that axis is ''align-self/end''; etc.

<div class=example>

For example, assuming an English-equivalent writing mode (horizontal-tb, ltr),

then the value ''span-x-start top'' resolves to

the "start" region of the vertical axis,

and the "start" and "center" regions of the horizontal axis,

so the default alignments will be ''align-self: end''

(making the element's bottom flush with the bottom of the "top" region)

and ''justify-self: end''

(making the element's end side flush with the end side of the "start+center" region).

<figure>

<img src="images/position-area-example.png" width=400>

<figcaption>

An example of ''position-area: span-x-start top'' positioning.

</figcaption>

</figure>

</div>

Note: When the [=default anchor element=]

is partially or completely outside of the pre-modified [=containing block=],

some of the [=position-area grid's=] rows or columns can be zero-sized.

<!-- Big Text: anchor()

███▌ █ █▌ ███▌ █▌ █▌ ███▌ ████▌ ██ ██

▐█ ▐█ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ ▐█

█▌ █▌ ██▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ ▐█

█▌ █▌ █▌▐█ █▌ █▌ █████▌ █▌ █▌ ████▌ █▌ ▐█

█████▌ █▌ ██▌ █▌ █▌ █▌ █▌ █▌ █▌▐█ █▌ ▐█

█▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ ▐█ █▌ ▐█

█▌ █▌ █▌ ▐▌ ███▌ █▌ █▌ ███▌ █▌ █▌ ██ ██

-->

The ''anchor()'' Function {#anchor-pos}

---------------------------------------------------

An [=absolutely-positioned=] element

can use the <dfn>anchor()</dfn> function

as a value in its [=inset properties=]

to refer to the position of one or more [=anchor elements=].

The ''anchor()'' function resolves to a <<length>>.

It is only valid to be used in the [=inset properties=].

<pre class=prod>

&lt;anchor()> = anchor( <<anchor-element>>? && <<anchor-side>>, <<length-percentage>>? )

<dfn><<anchor-element>></dfn> = <<dashed-ident>>

<dfn><<anchor-side>></dfn> = inside | outside

| top | left | right | bottom

| start | end | self-start | self-end

| <<percentage>> | center

</pre>

The ''anchor()'' function has three arguments:

* the <<anchor-element>> value

specifies how to find the [=anchor element=]

it will be drawing positioning information from.

Its possible values are:

<dl dfn-type=value dfn-for="anchor()">

: <dfn><<dashed-ident>></dfn>

:: Specifies the [=anchor name=] it will look for.

This name is a [=tree-scoped reference=].

: omitted

:: Selects the [=implicit anchor element=]

defined for the element,

if possible.

</dl>

See [=target anchor element=] for details.

* the <<anchor-side>> value

refers to the position of the corresponding side

of the [=target anchor element=].

Its possible values are:

<dl dfn-type=value dfn-for="anchor()">

: <dfn>inside</dfn>

: <dfn>outside</dfn>

:: Resolves to one of the [=anchor element's=] sides,

depending on which [=inset property=] it's used in.

''anchor()/inside'' refers to the same side as the [=inset property=]

(attaching the element to the "inside" of the anchor),

while ''anchor()/outside'' refers to the opposite.

: <dfn>top</dfn>

: <dfn>right</dfn>

: <dfn>bottom</dfn>

: <dfn>left</dfn>

:: Refers to the specified side of the [=anchor element=].

Note: These are only usable in the [=inset properties=]

in the matching axis.

For example, ''anchor()/left'' is usable in 'left', 'right',

or the logical [=inset properties=] that refer to the horizontal axis.

: <dfn>start</dfn>

: <dfn>end</dfn>

: <dfn>self-start</dfn>

: <dfn>self-end</dfn>

:: Refers to one of the sides of the [=anchor element=]

in the same axis as the [=inset property=] it's used in,

by resolving the keyword against the [=writing mode=]

of either the positioned element

(for ''anchor()/self-start'' and ''anchor()/self-end'')

or the positioned element's containing block

(for ''anchor()/start'' and ''anchor()/end'').

: <dfn><<percentage>></dfn>

: <dfn>center</dfn>

:: Refers to a position

a corresponding percentage between the ''anchor()/start'' and ''anchor()/end'' sides,

with ''0%'' being equivalent to ''anchor()/start''

and ''100%'' being equivalent to ''anchor()/end''.

''anchor()/center'' is equivalent to ''50%''.

* the optional <<length-percentage>> final argument is a fallback value,

specifying what the function should resolve to

if it's an [=invalid anchor function=].

An ''anchor()'' function representing a [=valid anchor function=]

resolves at [=computed value=] time

(using [=style & layout interleaving=])

to the <<length>> that would align the edge

of the positioned elements' [=inset-modified containing block=]

corresponding to the property the function appears in

with the specified border edge of the [=target anchor element=],

assuming that all [=scroll containers=]

between the [=target anchor element=]

and the positioned element's [=containing block=]

are scrolled to their initial scroll position

(but see [[#scroll]]).

Note: This means that [=transitions=] or [=animations=]

of a property using an [=anchor function=]

will work "as expected" for all sorts of possible changes:

the anchor element moving,

anchor elements being added or removed from the document,

the 'anchor-name' property being changed on anchors,

etc.

If the [=target anchor element=] is [=fragmented=],

the axis-aligned bounding rectangle

of the fragments' border boxes is used instead.

The positioned element

is additionally visually shifted

by its [=snapshotted scroll offset=],

as if by an additional ''translate()'' transform.

<div class=example>

For example,

in ''.bar { top: anchor(--foo top); }'',

the ''anchor()'' will resolve to the length

that'll line up the <code>.bar</code> element's top edge

with the ''--foo'' anchor's top edge.

On the other hand,

in ''.bar { bottom: anchor(--foo top); }'',

it will instead resolve to the length

that'll line up the <code>.bar</code> element's <em>bottom</em> edge

with the ''--foo'' anchor's top edge.

Since 'top' and 'bottom' values specify insets from different edges

(the top and bottom of the element's [=containing block=],

respectively),

the same ''anchor()'' will usually resolve to different lengths in each.

</div>

<div class=example>

Because the ''anchor()'' function resolves to a <<length>>,

it can be used in [=math functions=] like any other length.

For example, the following will set up the element

so that its [=inset-modified containing block=]

is centered on the [=anchor element=]

and as wide as possible without overflowing the [=containing block=]:

<pre highlight=css>

.centered-message {

position: fixed;

max-width: max-content;

justify-self: center;

--center: anchor(--x 50%);

--half-distance: min(

abs(0% - var(--center)),

abs(100% - var(--center))

);

left: calc(var(--center) - var(--half-distance));

right: calc(var(--center) - var(--half-distance));

bottom: anchor(--x top);

}

</pre>

This might be appropriate for an error message

on an <{input}> element,

for example,

as the centering will make it easier to discover

which input is being referred to.

</div>

<!-- Big Text: a-center

███▌ ███▌ █████▌ █ █▌ █████▌ █████▌ ████▌

▐█ ▐█ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌

█▌ █▌ █▌ █▌ ██▌ █▌ █▌ █▌ █▌ █▌

█▌ █▌ ████▌ █▌ ████ █▌▐█ █▌ █▌ ████ ████▌

█████▌ █▌ █▌ █▌ ██▌ █▌ █▌ █▌▐█

█▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ ▐█

█▌ █▌ ███▌ █████▌ █▌ ▐▌ █▌ █████▌ █▌ █▌

-->

Centering on the Anchor: the ''anchor-center'' value {#anchor-center}

------------------------------------------------------------------------

<pre class=propdef>

Name: justify-self, align-self, justify-items, align-items

New Values: anchor-center

</pre>

The [=self-alignment properties=] allow an [=absolutely-positioned=] element

to align itself within the [=inset-modified containing block=].

The existing values,

plus carefully chosen [=inset properties=],

are usually enough for useful alignment,

but a common case for anchored positioning--

centering over the anchor element--

requires careful and somewhat complex set-up to achieve.

The new <dfn value for="justify-self, align-self, justify-items, align-items">anchor-center</dfn> value

makes this case extremely simple:

if the positioned element has a [=default anchor element=],

then it is aligned so as to center itself

over the [=default anchor element=]

in the relevant axis.

Additionally,

any ''top/auto'' [=inset properties=] resolve to ''0''.

If the element is not [=absolutely positioned=],

or does not have a [=default anchor element=],

this value behaves as ''<self-position>/center''

and has no additional effect on how [=inset properties=] resolve.

Note: Similar to 'position-area',

when using ''anchor-center'',

if the anchor is too close to the edge of the element's

[=original containing block=],

by default it will "shift" from being purely centered,

to instead remain within the [=original containing block=].

See [[css-align-3#overflow-values]] for more details.

<!-- Big Text: scroll

███▌ ███▌ ████▌ ███▌ █▌ █▌

█▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌

█▌ █▌ █▌ █▌ █▌ █▌ █▌ █▌

███▌ █▌ ████▌ █▌ █▌ █▌ █▌

█▌ █▌ █▌▐█ █▌ █▌ █▌ █▌

█▌ █▌ █▌ █▌ █▌ ▐█ █▌ █▌ █▌ █▌

███▌ ███▌ █▌ █▌ ███▌ █████ █████

-->

Taking Scroll Into Account {#scroll}

------------------------------------------------------------------

Because scrolling is often done in a separate thread from layout in implementations for performance reasons,

but ''anchor()'' can result in both positioning changes

(which can be handled in the scrolling thread)

and layout changes

(which cannot),

''anchor()'' is defined to assume

all the [=scroll containers=] between the anchor element

and the positioned element's containing block

are at their initial scroll position.

This means a positioned element

will <em>not</em> be aligned with its anchor

if any of the scrollers are <em>not</em> at their initial positions.

To compensate for this without losing

the performance benefits of the separate scrolling thread,

we define: