-
Notifications
You must be signed in to change notification settings - Fork 646
/
Overview.bs
2326 lines (1923 loc) · 82.3 KB
/
Overview.bs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<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><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>
<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: