Editorial review: Document anchor-scope property #42227

chrisdavidmills · 2025-12-04T12:30:43Z

Description

Chrome 131 supports the anchor-scope property; see https://chromestatus.com/feature/5094192052436992. It is also supported in Safari 26, and behind a pref in Fx Nightly.

This PR documents anchor-scope.

Motivation

Additional details

Related issues and pull requests

Fixes #39295

github-actions · 2025-12-04T12:32:16Z

Preview URLs

Flaws (23)

Note! 1 document with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/CSS/Guides/Anchor_positioning/Using
Title: Using CSS anchor positioning
Flaw count: 1

unknown:
- Error parsing /shared-assets/images/diagrams/css/anchor-positioning/position-area.svg: No such file or directory (os error 2)

URL: /en-US/docs/Web/CSS/Reference/Properties/anchor-name
Title: anchor-name
Flaw count: 7

broken_links:
- Link /en-US/docs/Web/CSS/CSS_values_and_units/Value_definition_syntax#single_bar is a redirect
- Link /en-US/docs/Web/CSS/dashed-ident is a redirect
- Link /en-US/docs/Web/CSS/CSS_values_and_units/Value_definition_syntax#hash_mark is a redirect
macros:
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Value_processing which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Inheritance which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Value_processing which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_animated_properties which is a redirect

URL: /en-US/docs/Web/CSS/Reference/Properties/anchor-scope
Title: anchor-scope
Flaw count: 8

broken_links:
- Link /en-US/docs/Web/CSS/CSS_values_and_units/Value_definition_syntax#single_bar is a redirect
- Link /en-US/docs/Web/CSS/CSS_values_and_units/Value_definition_syntax#single_bar is a redirect
- Link /en-US/docs/Web/CSS/dashed-ident is a redirect
- Link /en-US/docs/Web/CSS/CSS_values_and_units/Value_definition_syntax#hash_mark is a redirect
macros:
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Value_processing which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Inheritance which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Value_processing which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_animated_properties which is a redirect

URL: /en-US/docs/Web/CSS/Reference/Properties/position-anchor
Title: position-anchor
Flaw count: 7

broken_links:
- Link /en-US/docs/Web/CSS/CSS_values_and_units/Value_definition_syntax#single_bar is a redirect
- Link /en-US/docs/Web/CSS/CSS_values_and_units/Value_definition_syntax#single_bar is a redirect
- Link /en-US/docs/Web/CSS/dashed-ident is a redirect
macros:
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Value_processing which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Inheritance which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_cascade/Value_processing which is a redirect
- Macro cssinfo produces link /en-US/docs/Web/CSS/CSS_animated_properties which is a redirect

(comment last updated: 2026-01-05 17:06:39)

estelle

oops, didn't realize this was in tech review... so sharing my few comments, but will wait til editorial to finish the review

files/en-us/web/css/guides/anchor_positioning/using/index.md

Co-authored-by: Estelle Weyl <[email protected]>

andruud

lgtm

files/en-us/web/css/reference/properties/anchor-scope/index.md

chrisdavidmills · 2025-12-08T15:41:52Z

Thanks for the review, @andruud; I'll move this one on to the editorial review stage now.

estelle

sorry, didn't realize this was ready for review.

files/en-us/web/css/guides/anchor_positioning/using/index.md

estelle · 2025-12-17T15:43:13Z

files/en-us/web/css/guides/anchor_positioning/using/index.md

+
+For example, if a document contains multiple repeated components, each with a positioned element tethered to an anchor, all the positioned elements will be anchored to the last anchor on the page unless each component uses a different anchor name. This is likely not the desired behavior.
+
+The {{cssxref("anchor-scope")}} property can fix this problem by making it so that each positioned element can only be anchored to an element within the same subtree of the element that has the scope set on it:


how about something like:

With the {{cssxref("anchor-scope")}} property, you can limit the visibility, or "scope', of an `anchor-name` value to a specific subtree, which enables the association of multiple same-named anchors with their own positioned elements within a single document:

I like the first half of the suggestion, but I felt like the second half was a bit confusing. In the next commit, I've updated it to:

The {{cssxref("anchor-scope")}} property can fix this problem by limiting the visibility, or "scope", of an anchor-name value to a specific subtree. The result is that each positioned element can only be anchored to an element within the same subtree of the element that has the scope set on it:

estelle · 2025-12-17T15:52:23Z

files/en-us/web/css/guides/anchor_positioning/using/index.md

+The {{cssxref("anchor-scope")}} property can fix this problem by making it so that each positioned element can only be anchored to an element within the same subtree of the element that has the scope set on it:
+
+- `anchor-scope: all` sets the scope so that _any_ `anchor-name` values set in the subtree can only be bound to by positioned elements in the same subtree.
+- `anchor-scope: --my-anchor` sets the scope so that the specified `anchor-name` value, when set in the subtree, can only be bound to by positioned elements in the same subtree.


suggest mentioning none is the default, and somehow alluding to the fact that it can be a comma separated list.

Good call. I've updated the second bullet to indicate that multiple comma-separated values can be set, and added a third bullet to explain the none value.

estelle · 2025-12-17T16:01:34Z

files/en-us/web/css/guides/anchor_positioning/using/index.md

+- `anchor-scope: all` sets the scope so that _any_ `anchor-name` values set in the subtree can only be bound to by positioned elements in the same subtree.
+- `anchor-scope: --my-anchor` sets the scope so that the specified `anchor-name` value, when set in the subtree, can only be bound to by positioned elements in the same subtree.
+
+For example, let's say you have an anchor and a anchor-positioned element inside a scoped container, and another positioned element outside the container:


the intro says this is useful when we have multiple elements with the same anchor name. Let show an example with multiple anchors and positioned elements.

maybe use an ordered list with 3 sets, and do something like

<li> <div class="anchor">⚓︎⚓︎⚓︎</div>` <div class="positioned">Positioned 3</div> </li>

as the last in the list.

OK, I've rewritten the example to include three sets.

estelle · 2025-12-17T16:04:37Z

files/en-us/web/css/guides/anchor_positioning/using/index.md

+  background: orange;
+  width: fit-content;
+  padding: 3px;
+  position: absolute;


end the hidden part here (i can't add closing tick marks in this editor)

Suggested change

position: absolute;

```css live-sample___anchor-scope

li {

anchor-scope: --my-anchor;

}

.positioned {

position: absolute;

estelle · 2025-12-17T22:48:56Z

files/en-us/web/css/reference/properties/anchor-scope/index.md

+
+- `all`: The scope for positioning elements relative to anchor elements that are descendants of the `<section>` elements is limited to positioned elements that are themselves descendants of the `<section>` elements, regardless of the `anchor-name` value used to associate them. As a result, the positioned elements inside the `<section>` elements ("Positioned 1") are anchor-positioned as expected, but the positioned element outside the `<section>` elements ("Positioned 2") is not anchor-positioned. It is out of scope.
+- `--my-anchor`: The scope for positioning elements relative to anchor elements that are descendants of the `<section>` elements is limited to positioned elements that are themselves descendants of the `<section>` elements, only if the `--my-anchor` `anchor-name` is used to associate them. As a result, the positioned elements inside the `<section>` elements ("Positioned 1") are anchor-positioned as expected, and the positioned element outside the `<section>` elements ("Positioned 2") is also anchor-positioned as expected. In the former case, the positioned elements are inside the set scope, and in the latter case, the positioned element is not affected by the set scope, as it is using an anchor name outside the scope (<code>&#8209;&#8209;another-anchor</code>). The "Positioned 2" element is positioned relative to the last anchor element in the source that has the matching anchor name.
+- `none`: No anchor scope is set on the `<section>` elements. As a result, all of the positioned elements are positioned relative to the last anchor element in the source order.


Suggested change

- `none`: No anchor scope is set on the `<section>` elements. As a result, all of the positioned elements are positioned relative to the last anchor element in the source order.

- `none`: As no anchor scope is set on the `<section>` elements, all of the positioned elements are positioned relative to the last anchor element in the source order.

estelle · 2025-12-17T22:54:20Z

files/en-us/web/css/reference/properties/anchor-scope/index.md

+
+### Comparing different `anchor-scope` values
+
+This example allows you to apply different `anchor-scope` values to multiple containers, to demonstrate the effects of each.


maybe something like:

This example demonstrates the different `anchor-scope` values by allowing you to apply different `anchor-scope` values to multiple containers, all containing anchors with the same `anchor-name` value.

estelle · 2025-12-17T22:55:48Z

files/en-us/web/css/reference/properties/anchor-scope/index.md

+
+Check out the initial positioning effect applied to the positioned elements with `anchor-scope: all` set on the `<section>` elements, and then try selecting the other available `anchor-scope` values to see what their effect is. You should observe the following:
+
+- `all`: The scope for positioning elements relative to anchor elements that are descendants of the `<section>` elements is limited to positioned elements that are themselves descendants of the `<section>` elements, regardless of the `anchor-name` value used to associate them. As a result, the positioned elements inside the `<section>` elements ("Positioned 1") are anchor-positioned as expected, but the positioned element outside the `<section>` elements ("Positioned 2") is not anchor-positioned. It is out of scope.


move most of these explanations, made more generic, into the description area values section.

I don't want to do that. I think they are useful here, explained in the context of the example. It is tricky to understand the effects these values have, so this serves as a useful recap.

we can keep this here, but add the guts to the description, and make this a summary of what is happening, allowing the explanation to be in the description with a "select the [example of the `all` value](#anchor)" lingo with a link to this example

files/en-us/web/css/reference/properties/position-anchor/index.md

Co-authored-by: Estelle Weyl <[email protected]>

estelle

left some comments.

I've been thinking about the non-breaking dashes. I think we should stick with regular dashes. breaking double dashes hasn't been an issue thus far on MDN, and they are not valid. https://codepen.io/estelle/pen/WbxwRPa

estelle · 2026-01-06T12:05:12Z

files/en-us/web/css/reference/properties/anchor-scope/index.md

+
+Anchor scopes only affect **explicit anchor associations**, that is, those made between an anchor element with an `anchor-name` set on it, and a positioned element referencing the anchor element's anchor name in its `position-anchor` value. Anchor scopes do not affect [implicit anchor associations](/en-US/docs/Web/CSS/Guides/Anchor_positioning/Using#implicit_anchor_association).
+
+For more information on anchor features and usage, see the [CSS anchor positioning](/en-US/docs/Web/CSS/Guides/Anchor_positioning) module landing page and the [Using CSS anchor positioning](/en-US/docs/Web/CSS/Guides/Anchor_positioning/Using) guide.


They aren't "landing pages". A landing page serves as a menu, of sorts, for its subpages. #42644 removes the misnomer in the css section

estelle · 2026-01-06T13:44:57Z

files/en-us/web/css/reference/properties/anchor-scope/index.md

+- `anchor-scope: <dashed-ident>#` sets the scope so that the specified `anchor-name` values, when set in the subtree, can only be bound to by positioned elements in the same subtree.
+- `anchor-scope: none` is the default value; it specifies that no anchor scoping is set.
+
+If you have, for example, three `anchor-name` values set inside a subtree (say, <code>&#8209;&#8209;anchor1</code>, <code>&#8209;&#8209;anchor2</code>, and <code>&#8209;&#8209;anchor3</code>), setting <code>anchor-scope: &#8209;&#8209;anchor1, &#8209;&#8209;anchor2, &#8209;&#8209;anchor3</code> on the top-level element of the subtree would be equivalent to setting `anchor-scope: all`.


Suggested change

If you have, for example, three `anchor-name` values set inside a subtree (say, <code>‑‑anchor1</code>, <code>‑‑anchor2</code>, and <code>‑‑anchor3</code>), setting <code>anchor-scope: ‑‑anchor1, ‑‑anchor2, ‑‑anchor3</code> on the top-level element of the subtree would be equivalent to setting `anchor-scope: all`.

If you have, for example, three `anchor-name` values set inside a subtree (say, `‑‑anchor1`, `‑‑anchor2`, and `‑‑anchor3`), setting `anchor-scope: ‑‑anchor1, ‑‑anchor2, ‑‑anchor3` on the top-level element of the subtree would be equivalent to setting `anchor-scope: all`.

I used non-breaking hyphens.

estelle · 2026-01-06T13:46:27Z

files/en-us/web/css/reference/properties/anchor-scope/index.md

+
+#### CSS
+
+We start by specifying our anchor elements as anchors by giving them two {{cssxref("anchor-name")}} values: <code>&#8209;&#8209;my-anchor</code> and `--another-anchor`.


I was thinking we might want to globally replace all to non-breaking anchor characters, but i don't think a breaking double dash is an issue (we don't do this anywhere else), so i recommend changing all to ndashes and getting rid of the <code>s.

estelle · 2026-01-06T14:42:30Z

files/en-us/web/css/reference/properties/anchor-scope/index.md

+Check out the initial positioning effect applied to the positioned elements with `anchor-scope: all` set on the `<section>` elements, and then try selecting the other available `anchor-scope` values to see what their effect is. You should observe the following:
+
+- `all`: The scope for positioning elements relative to anchor elements that are descendants of the `<section>` elements is limited to positioned elements that are themselves descendants of the `<section>` elements, regardless of the `anchor-name` value used to associate them. As a result, the positioned elements inside the `<section>` elements ("Positioned 1–3") are anchor-positioned as expected, but the positioned element outside the `<section>` elements ("Positioned 4") is not anchor-positioned. It is out of scope.
+- `--my-anchor`: The scope for positioning elements relative to anchor elements that are descendants of the `<section>` elements is limited to positioned elements that are themselves descendants of the `<section>` elements, only if the `--my-anchor` `anchor-name` is used to associate them. As a result, the positioned elements inside the `<section>` elements ("Positioned 1–3") are anchor-positioned as expected, and the positioned element outside the `<section>` elements ("Positioned 4") is also anchor-positioned as expected. In the former case, the positioned elements are inside the set scope, and in the latter case, the positioned element is not affected by the set scope, as it is using an anchor name outside the scope (<code>&#8209;&#8209;another-anchor</code>). The "Positioned 4" element is positioned relative to the last anchor element in the source that has the matching anchor name.


Add the explanation provided here to the description. Currently, the description does not expand at all on the value section content. Examples should add to what is covered in the description, illustrating what is explained there. The examples should illustrate what was already covered. The content here is good, but will be missed by many readers.

estelle · 2026-01-06T14:48:19Z

files/en-us/web/css/reference/properties/anchor-scope/index.md

+
+.positioned,
+.positioned2 {
+  background: orange;


box-shadow: 3px 3px 3px rgba(0 0 0 / .2) does the trick - when 3 are on top of each other it's apparent.

Document anchor-scope property

ce29ef1

chrisdavidmills requested a review from a team as a code owner December 4, 2025 12:30

chrisdavidmills requested review from estelle and removed request for a team December 4, 2025 12:30

github-actions bot added the Content:CSS Cascading Style Sheets docs label Dec 4, 2025

chrisdavidmills changed the title ~~Document anchor-scope property~~ Technical review: Document anchor-scope property Dec 4, 2025

github-actions bot added the size/m [PR only] 51-500 LoC changed label Dec 4, 2025

estelle reviewed Dec 4, 2025

View reviewed changes

files/en-us/web/css/guides/anchor_positioning/using/index.md Show resolved Hide resolved

files/en-us/web/css/guides/anchor_positioning/using/index.md Outdated Show resolved Hide resolved

files/en-us/web/css/guides/anchor_positioning/using/index.md Outdated Show resolved Hide resolved

chrisdavidmills and others added 2 commits December 4, 2025 16:49

Update files/en-us/web/css/guides/anchor_positioning/using/index.md

a2d15ec

Co-authored-by: Estelle Weyl <[email protected]>

Update files/en-us/web/css/guides/anchor_positioning/using/index.md

6bc0d77

Co-authored-by: Estelle Weyl <[email protected]>

andruud reviewed Dec 8, 2025

View reviewed changes

files/en-us/web/css/reference/properties/anchor-scope/index.md Outdated Show resolved Hide resolved

files/en-us/web/css/reference/properties/anchor-scope/index.md Outdated Show resolved Hide resolved

Fixes for andruud review comments

ea31cf4

chrisdavidmills changed the title ~~Technical review: Document anchor-scope property~~ Editorial review: Document anchor-scope property Dec 8, 2025

chrisdavidmills requested a review from estelle December 8, 2025 15:42

estelle reviewed Dec 17, 2025

View reviewed changes

chrisdavidmills and others added 3 commits January 5, 2026 13:39

Merge branch 'main' into anchor-scope

b625e6f

Update files/en-us/web/css/guides/anchor_positioning/using/index.md

038752b

Co-authored-by: Estelle Weyl <[email protected]>

Fixes for estelle review comments

7988951

chrisdavidmills requested a review from estelle January 5, 2026 17:05

estelle reviewed Jan 6, 2026

View reviewed changes


		For example, if a document contains multiple repeated components, each with a positioned element tethered to an anchor, all the positioned elements will be anchored to the last anchor on the page unless each component uses a different anchor name. This is likely not the desired behavior.

		The {{cssxref("anchor-scope")}} property can fix this problem by making it so that each positioned element can only be anchored to an element within the same subtree of the element that has the scope set on it:

-  position: absolute;
+```css live-sample___anchor-scope
+li {
+  anchor-scope: --my-anchor;
+}
+.positioned {
+  position: absolute;

	- `none`: No anchor scope is set on the `<section>` elements. As a result, all of the positioned elements are positioned relative to the last anchor element in the source order.
	- `none`: As no anchor scope is set on the `<section>` elements, all of the positioned elements are positioned relative to the last anchor element in the source order.


		### Comparing different `anchor-scope` values

		This example allows you to apply different `anchor-scope` values to multiple containers, to demonstrate the effects of each.


		Check out the initial positioning effect applied to the positioned elements with `anchor-scope: all` set on the `<section>` elements, and then try selecting the other available `anchor-scope` values to see what their effect is. You should observe the following:

		- `all`: The scope for positioning elements relative to anchor elements that are descendants of the `<section>` elements is limited to positioned elements that are themselves descendants of the `<section>` elements, regardless of the `anchor-name` value used to associate them. As a result, the positioned elements inside the `<section>` elements ("Positioned 1") are anchor-positioned as expected, but the positioned element outside the `<section>` elements ("Positioned 2") is not anchor-positioned. It is out of scope.


		Anchor scopes only affect explicit anchor associations, that is, those made between an anchor element with an `anchor-name` set on it, and a positioned element referencing the anchor element's anchor name in its `position-anchor` value. Anchor scopes do not affect [implicit anchor associations](/en-US/docs/Web/CSS/Guides/Anchor_positioning/Using#implicit_anchor_association).

		For more information on anchor features and usage, see the [CSS anchor positioning](/en-US/docs/Web/CSS/Guides/Anchor_positioning) module landing page and the [Using CSS anchor positioning](/en-US/docs/Web/CSS/Guides/Anchor_positioning/Using) guide.

	If you have, for example, three `anchor-name` values set inside a subtree (say, <code>‑‑anchor1</code>, <code>‑‑anchor2</code>, and <code>‑‑anchor3</code>), setting <code>anchor-scope: ‑‑anchor1, ‑‑anchor2, ‑‑anchor3</code> on the top-level element of the subtree would be equivalent to setting `anchor-scope: all`.
	If you have, for example, three `anchor-name` values set inside a subtree (say, `‑‑anchor1`, `‑‑anchor2`, and `‑‑anchor3`), setting `anchor-scope: ‑‑anchor1, ‑‑anchor2, ‑‑anchor3` on the top-level element of the subtree would be equivalent to setting `anchor-scope: all`.


		#### CSS

		We start by specifying our anchor elements as anchors by giving them two {{cssxref("anchor-name")}} values: <code>‑‑my-anchor</code> and `--another-anchor`.

Editorial review: Document anchor-scope property #42227

Are you sure you want to change the base?

Editorial review: Document anchor-scope property #42227

Uh oh!

Conversation

chrisdavidmills commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

github-actions bot commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

estelle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

andruud left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

chrisdavidmills commented Dec 8, 2025

Uh oh!

estelle left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

estelle Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

estelle left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

chrisdavidmills commented Dec 4, 2025 •

edited

Loading

github-actions bot commented Dec 4, 2025 •

edited

Loading

estelle Jan 6, 2026 •

edited

Loading