Last updated: First published:
The View Transition API
The View Transition API is a rather new API. In this section you can find…
- …some basic examples of same-document and cross document view transitions.
- …information about the structure of the pseudo-elements of the API.
- …and about the mechanisms of the default animations.
- …some background on how to style view transitions.
- …details on how to use the JavaScript API for same-document view transitions.
- …all there is to know about the stacking behavior of view transitions.
While I add more pages, I’m also happy that I can offer some links to previous work on the astro-vtbot package↗:
- An Overview↗ and a Details↗ article on the API
- An in depth same-document example↗
-
Level 1: CSS View Transitions Module Level 1 (Editor’s Draft) https://drafts.csswg.org/css-view-transitions-1/↗
-
Level 2: CSS View Transitions Module Level 2 (Editor’s Draft) https://drafts.csswg.org/css-view-transitions-2/↗
| When | What | Where |
|---|---|---|
| 2025-10-17 | The view transition object offers a 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↗ |
| 2025-10-02 | 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↗ |
| 2025-10-02 | The 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↗ |
| 2025-10-02 | The new value view-transition for the contain property ensures that view transition names are not visible outside a subtree | Level 2, View Transition Name Isolation↗ |
| 2025-08-25 | Expose the currently active view transition object as activeViewTransition on the document, or on an element for scoped view transitions. | Level 2, Exposing current transition↗ |
| 2025-06-18 | The old, new, and image-pair pseudos now also inherit the timing function, iteration count, direction, play state animation properties. | Level 1, User Agent Styles↗ |
| 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() pseudo-element gets automatically copied over from the original element. | Level 2, Group Children↗ |
| 2025-03-24 | Change to view-transition-name: auto when the element has an id property: Instead of using the id as view transition name, now generates a random name like match-element. | Level 2, View Transition Name↗ |
| 2025-02-20 | Added view-transition-name: match-element; for automatically assigning element specific view transition names. | Level 2, View Transition Name↗ |
These may or may not make it into the spec.
| When | What | Where |
|---|---|---|
| 2025-09-18 | Support two phases for cross-document view transitions: instead of waiting for enough content of the new page to load before starting animations, begin them on the old page by hopping through a quickly computable preview state for a smoother user experience. | Explainer: Two-phase view transition↗ |
| 2025-08-20 | Allow the view transition pseudo-elements inside the :has() pseudo-class. | #12630↗ |
| 2025-08-05 | Introduce DOM nodes as proxies to pseudo-elements. This would for example allow us to define an event listener for ::view-transition-new(button) using such a proxy. | #12575↗ |
| 2025-06-18 | Also copy border radius and corner shape form old and new original elements and animate the ::view-transition-group-children() from old to new values. | #12357↗, #12363↗ |
| 2025-05-28 | User defined view transition names must not start with -ua- as those are reserved for the user agent, e.g. for match-element and auto. | #12241↗ |
| 2025-01-29 | ::view-transition-new(*) { pointer-events: auto } to forward pointer events from the pseudo-element to the original element. | #11596↗ |
| 2024-06-13 | transitionRoot property of the ViewTransition object reports the DOM element the scoped view transition was called on. | comment on #9908↗ |
- The Documentation of the View Transition API on MDN https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API↗
- The Level 1 View Transition API Explainer at W3C/WICG: https://github.com/WICG/view-transitions/blob/main/explainer.md↗
- The Level 2 View Transition API Explainer at W3C/WICG: https://github.com/WICG/view-transitions/blob/main/cross-doc-explainer.md#pageconceal↗
Highly recommended introductions by examples and deep dives:
-
Jake Archibald’s Same-document view transitions for single-page applications https://developer.chrome.com/docs/web-platform/view-transitions/same-document↗
-
Bramus’ Cross-document view transitions for multi-page applications https://developer.chrome.com/docs/web-platform/view-transitions/cross-document↗
-
Jake’s eye-opening article on how to handle aspect ratio↗
-
A collection of same-page and cross-page examples↗ from Bramus.