Document: startViewTransition() method

Baseline 2025 *

Newly available

Since ⁨October 2025⁩, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Some parts of this feature may have varying levels of support.

ThestartViewTransition() method of theDocument interface starts a new same-document (SPA)view transition and returns aViewTransition object to represent it.

WhenstartViewTransition() is invoked, a sequence of steps is followed as explained inThe view transition process.

An optional callback function typically invoked to update the DOM during the SPA view transition process, which returns aPromise. The callback is invoked once the API has taken a snapshot of the current page. When the promise returned by the callback fulfills, the view transition begins in the next frame. If the promise returned by the callback rejects, the transition is abandoned.

optionsOptional

An object containing options to configure the view transition. It can include the following properties:

updateOptional: The sameupdateCallback function described above. Defaults tonull.
typesOptional: An array of strings. These strings act as class names or identifiers for the transition, allowing you to selectively apply CSS styles or run different JavaScript logic based on the type of transition occurring. Defaults to an empty sequence.

Return value

AViewTransition object instance.

Examples

Using a same-document view transition

In this same-document view transition, we check if the browser supports view transitions.If there's no support, we set the background color using a fallback method which is applied immediately.Otherwise, we can safely calldocument.startViewTransition() with animation rules that we define in CSS.

html

<main>  <section></section>  <button>Change color</button></main>

We are setting theanimation-duration to 2 seconds using the::view-transition-group pseudo-element.

css

html {  --bg: indigo;}main {  display: flex;  flex-direction: column;  gap: 5px;}section {  background-color: var(--bg);  height: 60px;  border-radius: 5px;}::view-transition-group(root) {  animation-duration: 2s;}

const colors = ["darkred", "darkslateblue", "darkgreen"];const colBlock = document.querySelector("section");let count = 0;const updateColor = () => {  colBlock.style = `--bg: ${colors[count]}`;  count = count !== colors.length - 1 ? ++count : 0;};const changeColor = () => {  // Fallback for browsers that don't support View Transitions:  if (!document.startViewTransition) {    updateColor();    return;  }  // With View Transitions:  const transition = document.startViewTransition(() => {    updateColor();  });};const changeColorButton = document.querySelector("#change-color");changeColorButton.addEventListener("click", changeColor);changeColorButton.addEventListener("keypress", changeColor);

If view transitions are supported, clicking the button will transition the color from one to another over 2 seconds.Otherwise, the background color is set using a fallback method, without any animation.