Element: startViewTransition() method

Syntax

startViewTransition()
startViewTransition(updateCallback)
startViewTransition(options)

Parameters

updateCallback Optional

A callback function, invoked to update the element's DOM tree during the SPA view transition process, which returns a Promise. 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.

options Optional

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

update Optional

The same updateCallback function described above. Defaults to null.

types Optional

An array of strings representing the types applied to the view transition. View transition types enable selective application of CSS styles or JavaScript logic based on the type of transition occurring. Defaults to an empty array.

Return value

A ViewTransition object instance.

Description

Calling Element.startViewTransition() on an element creates a view transition scoped to that particular element's DOM subtree. Any DOM changes performed inside the startViewTransition() callback will only transition if those updates happen inside the calling element's DOM subtree. The element is referred to as the root of the view transition, and the DOM subtree is referred to as the scope of the view transition.

An element-scoped view transition's pseudo-element tree is placed inside the transition root element, for example, if we were running a view transition on a link:

<a href="#">
  ├─ ::view-transition
  │  └─ ::view-transition-group(root)
  │     └─ ::view-transition-image-pair(root)
  │        ├─ ::view-transition-old(root)
  │        └─ ::view-transition-new(root)
  |
  |
  "Link text"
</a>

Element-scoped view transitions have many advantages over their document-scoped counterparts:

• You can run more than one at a time.
• When running, only the view transition's scope ceases to be interactive until the transition is finished; the rest of the page continues to be interactive. Document-scoped view transitions render the entire page non-interactive until the transition is complete.
• The transition pseudo-element tree only sits over the top of the element scope, not the entire page, meaning that you don't get the same issues associated with stacked elements disappearing underneath the updating part of the page when a document-scoped transition animation starts.
• If the contents of the scope are clipped using overflow, they will stay clipped while undergoing a view transition. Document-scoped view transitions spill out of clipping containers because their pseudo-element trees are drawn over the top of the entire page.

Examples

See Using element-scoped view transitions for other examples.

Basic usage

This example demonstrates using an element-scoped view transition to smoothly animate the DOM changes to a slideshow contained within a page when a button is pressed.

HTML

We include a <section> element to represent our slideshow, a <button> to press to change the slide content, and some surrounding <p> content.

<p>
  I'm baby xOXO bespoke cupidatat PBR&B, affogato cronut 3 wolf moon ea narwhal
  asymmetrical.
</p>
<section>Slide 1</section>
<button>Update slide</button>
<p>
  Kombucha laborum tempor iceland pour-over. Keytar in echo park gorpcore
  bespoke.
</p>

CSS

In our CSS, we use flexbox to center the slide's content, and set the animation-duration of the view transition to 1s via the ::view-transition-group pseudo-element.

html {
  font-family: sans-serif;
}
section {
  height: 200px;
  font-size: 2rem;
  background-color: green;
}
button {
  position: absolute;
  top: 5px;
  right: 5px;
}

section {
  display: flex;
  justify-content: center;
  align-items: center;
}
::view-transition-group(root) {
  animation-duration: 1s;
}

JavaScript

In our script, we start by grabbing references to our <section> and <button> elements, and adding an event listener to the button.

const slide = document.querySelector("section");
const btn = document.querySelector("button");
btn.addEventListener("click", handleClick);

Next, we define a function called updateSlide(), which toggles the content and background color of the slide between two sets of values.

function updateSlide() {
  if (slide.textContent === "Slide 1") {
    slide.textContent = "Slide 2";
    slide.style.backgroundColor = "orange";
  } else {
    slide.textContent = "Slide 1";
    slide.style.backgroundColor = "green";
  }
}

Finally, we define the event handler function, handleClick(). When the button is clicked, we first check whether Element.startViewTransition() exists, and if not, just run the updateSlide() button and return. This ensures that the update will still work in non-supporting browsers, albeit without the animation. If Element.startViewTransition() is supported, we call it on the <section> element, and call updateSlide() inside its callback.

function handleClick() {
  if (!slide.startViewTransition) {
    updateSlide();
    return;
  }

  const transition = slide.startViewTransition(() => {
    updateSlide();
  });
}

Result

Click the button to update the slide element DOM and see the view transition.

Specifications

Browser compatibility

See also

• Element.activeViewTransition
• :active-view-transition pseudo-class
• :active-view-transition-type() pseudo-class
• View Transition API
• Using the View Transition API
• Using view transition types
• Using element-scoped view transitions