ViewTransition

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

TheViewTransition interface of theView Transition API represents an active view transition, and provides functionality to react to the transition reaching different states (e.g., ready to run the animation, or animation finished) or skip the transition altogether.

This object type is made available in the following ways:

In the case of same-document (SPA) transitions, it is returned by thedocument.startViewTransition() method.
In the case of cross-document (MPA) transitions, it is made available:
- In the outgoing page via thepageswap event object'sPageSwapEvent.viewTransition property.
- In the inbound page via thepagereveal event object'sPageRevealEvent.viewTransition property.

When a view transition is triggered by astartViewTransition() call (or a page navigation in the case of MPA transitions), a sequence of steps is followed as explained inThe view transition process. This also explains when the different promises fulfill.

Instance properties

ViewTransition.finishedRead only: APromise that fulfills once the transition animation is finished, and the new page view is visible and interactive to the user.
ViewTransition.readyRead only: APromise that fulfills once the pseudo-element tree is created and the transition animation is about to start.
ViewTransition.updateCallbackDoneRead only: APromise that fulfills when the promise returned by thedocument.startViewTransition() method's callback fulfills.

Instance methods

skipTransition(): Skips the animation part of the view transition, but doesn't skip running thedocument.startViewTransition() callback that updates the DOM.

Examples

In the following SPA example, theViewTransition.ready promise is used to trigger a custom circular reveal view transition emanating from the position of the user's cursor on click, with animation provided by theWeb Animations API.

// Store the last click eventlet lastClick;addEventListener("click", (event) => (lastClick = event));function spaNavigate(data) {  // Fallback for browsers that don't support this API:  if (!document.startViewTransition) {    updateTheDOMSomehow(data);    return;  }  // Get the click position, or fallback to the middle of the screen  const x = lastClick?.clientX ?? innerWidth / 2;  const y = lastClick?.clientY ?? innerHeight / 2;  // Get the distance to the furthest corner  const endRadius = Math.hypot(    Math.max(x, innerWidth - x),    Math.max(y, innerHeight - y),  );  // Create a transition:  const transition = document.startViewTransition(() => {    updateTheDOMSomehow(data);  });  // Wait for the pseudo-elements to be created:  transition.ready.then(() => {    // Animate the root's new view    document.documentElement.animate(      {        clipPath: [          `circle(0 at ${x}px ${y}px)`,          `circle(${endRadius}px at ${x}px ${y}px)`,        ],      },      {        duration: 500,        easing: "ease-in",        // Specify which pseudo-element to animate        pseudoElement: "::view-transition-new(root)",      },    );  });}

This animation also requires the following CSS, to turn off the default CSS animation and stop the old and new view states from blending in any way (the new state "wipes" right over the top of the old state, rather than transitioning in):

css

::view-transition-image-pair(root) {  isolation: auto;}::view-transition-old(root),::view-transition-new(root) {  animation: none;  mix-blend-mode: normal;  display: block;}