Skip to content

Commit 4af1cea

Browse files
martrappCopilot
andcommitted
Update documentation to clarify usage of view-transition-scope and its impact on view transition names
Co-authored-by: Copilot <copilot@github.com>
1 parent 362754b commit 4af1cea

3 files changed

Lines changed: 9 additions & 11 deletions

File tree

src/content/docs/basics/api.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,13 +34,13 @@ While I add more pages, I'm also happy that I can offer some links to previous w
3434

3535
|When|What|Where|
3636
|---|---|---|
37-
|2026-03-09|`view-transition-scope: auto` (_outdated_) was superseded by `view-transition-scope: all`. You can use this property to hide view transition names inside a DOM subtree from view transitions started outside of it.|[view-transition-scope](https://drafts.csswg.org/css-view-transitions-2/#view-transition-scope-prop)
37+
|2026-03-09|`view-transition-scope: auto` (_outdated_) was superseded by [`view-transition-scope: all`](/basics/javascript/#view-transition-scope). You can use this property to hide view transition names inside a DOM subtree from view transitions started outside of it.|[view-transition-scope](https://drafts.csswg.org/css-view-transitions-2/#view-transition-scope-prop)
3838
|2026-01-26|`contain: view-transition` (_outdated_) was superseded by `view-transition-scope: auto` (_outdated_). |[view-transition-scope](https://drafts.csswg.org/css-view-transitions-2/#view-transition-scope-prop)
3939
||Level 1 of the spec was merged into Level 2. Level 1 is only for historical reference. Development of the API now happens solely in the Level 2 document.||
4040
|2025-10-17|The view transition object offers a [`waitUntil()`](/basics/javascript/#waituntil) function that can be called with a promise. Now the view transitions `finished` promise does not only wait for the animations on pseudo-elements to end, but also waits for all promises passed via `waitUntil()` to settle.|[Level 2, waitUntil](https://drafts.csswg.org/css-view-transitions-2/#dom-viewtransition-waituntil)|
4141
|2025-10-02|[Scoped view transitions](/basics/javascript/#scoped-view-transitions), where `startViewTransition()` can be called on DOM elements. To distinguish (element-)scoped view transitions from what we had before, cross-document view transitions and view transitions started with `document.startViewTransition()` might also be called _global_ view transitions.|[Level 2, Scoped View Transitions](https://drafts.csswg.org/css-view-transitions-2/#scoped-vt)
4242
|2025-10-02| The [`transitionRoot`](/basics/javascript/#transitionroot) property of the view transition object returns the root element of a scoped view transition. For a global view transition it returns the `documentElement`|[Level 2, transitionRoot](https://drafts.csswg.org/css-view-transitions-2/#dom-viewtransition-transitionroot)|
43-
|2025-10-02|A new value `view-transition` (_outdated_) for the `contain` property was introduced. In March 2026, it was superseded by `view-transition-scope: all`, which ensures that view transition names are not visible outside a subtree|[Level 2, View Transition Name Isolation](https://drafts.csswg.org/css-view-transitions-2/#view-transition-scope-prop)|
43+
|2025-10-02|A new value `view-transition` (_outdated_) for the `contain` property was introduced. In March 2026, it was superseded by [`view-transition-scope: all`](/basics/javascript/#view-transition-scope), which ensures that view transition names are not visible outside a subtree|[Level 2, View Transition Name Isolation](https://drafts.csswg.org/css-view-transitions-2/#view-transition-scope-prop)|
4444
|2025-08-25|Expose the currently active view transition object as [`activeViewTransition`](/basics/javascript/#checking-for-an-active-view-transition) on the document, or on an element for scoped view transitions.| [Level 2, Exposing current transition](https://drafts.csswg.org/css-view-transitions-2/#active-view-transition) |
4545
|2025-06-18| The `old`, `new`, and `image-pair` pseudos now also [inherit](/basics/styling/#inherited-animation-properties) the timing function, iteration count, direction, play state animation properties.|[Level 1, User Agent Styles](https://drafts.csswg.org/css-view-transitions-1/#ua-styles)
4646
|2025-06-16| Nested view transition groups are children of a new pseudo-element, which is the sibling of the image pair. The border width of this [`::view-transition-group-children()`](/basics/pseudos/#nested-view-transition-groups) pseudo-element gets automatically copied over from the original element.|[Level 2, Group Children](https://drafts.csswg.org/css-view-transitions-2/#view-transition-group-children-pseudo)|

src/content/docs/basics/javascript.mdx

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -170,17 +170,15 @@ Scoped view transitions are not widely supported jet. If your [browser supports]
170170

171171
#### view-transition-scope
172172

173-
To avoid conflicts between multiple scoped view transitions that target the same elements, the API adds
174-
```css
175-
view-transition-scope: all;
176-
```
177-
to the transition root. The transition root is either the document root or the element on which `element.startViewTransition()` was called. This is not fully automatic yet. As of Chrome 146.0.7665.0, it still requires explicit handling. When automatically inserted by the API, this property exists only for the lifetime of the triggering view transition. The only valid values for `view-transition-scope` are `all` and `none`.
173+
[`view-transition-scope`](https://drafts.csswg.org/css-view-transitions-2/#view-transition-scope-prop) is a relatively new CSS property currently supported only in Chrome.
174+
175+
It defines a visibility boundary for view transition names. The only valid values for `view-transition-scope` are `all` and `none`.
178176

179-
`view-transition-scope` defines a visibility boundary for view transition names. When it is set to `all` on an element, all view transition names defined within that element's DOM subtree are hidden from view transitions that are rooted outside of that subtree.
177+
When it is set to `all` on an element, all view transition names defined within that element's DOM subtree are hidden from view transitions rooted outside that subtree.
180178

181-
Without additional precautions, elements effectively get claimed by the first view transition that encounters them. This can lead to accidental coupling between unrelated transitions that just happen to reference the same elements.
179+
The API automatically inserts `view-transition-scope: all` at the transition root of an active view transition, and the property exists only while that view transition is active. The transition root is either the document root or the element on which `element.startViewTransition()` was called.
182180

183-
To avoid this, it might be better to define these boundaries explicitly. By setting `view-transition-scope: all` ahead of time on elements that may act as view transition roots, you can clearly assign which elements belong to which transition and prevent unintended interactions between concurrent or overlapping view transitions.
181+
Without additional precautions, elements can effectively be claimed by the first view transition that encounters them. This can lead to accidental coupling between unrelated transitions that happen to reference the same elements. To avoid this, it can be better to define these boundaries explicitly. By setting `view-transition-scope: all` ahead of time on elements that may act as view transition roots, you can clearly assign which elements belong to which transition and prevent unintended interactions between concurrent or overlapping view transitions.
184182

185183

186184

src/content/docs/basics/pseudos.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,7 @@ You can also use CSS properties to hide view transition names:
203203
</div>
204204

205205

206-
Here, `view-transition-scope` is a relatively new CSS property that is currently supported only in Chrome. With the value `all`, it hides the view transition names of its subtree without changing how the elements are rendered.
206+
[`view-transition-scope`](/basics/javascript/#view-transition-scope) hides the view transition names of its subtree without changing how the elements are rendered.
207207
It hides the names from view transitions rooted at an ancestor of the scoped element, but not from a view transition rooted at the scoped element itself or its descendants.
208208

209209
With these mechanisms for hiding view transition names, you can use the same `view-transition-name` multiple times within the same DOM, provided that all but one instance are hidden.

0 commit comments

Comments
 (0)