View Transitions API: Animate Between DOM States

Why it exists

Animating changes between application views has always been difficult. It required significant JavaScript and CSS to manage the old and new content, prevent user interaction bugs, and handle accessibility issues like focus loss. For traditional multi-page websites, smooth cross-page transitions were simply impossible.

The mental model

Think of the View Transitions API as telling the browser: "I'm about to change the DOM; please figure out how to animate it smoothly." The browser takes a snapshot of the page's current state, lets you make your DOM changes, takes a snapshot of the new state, and then animates between the two. It handles all the tricky parts of layering and timing.

How it works

For a Single-Page App (SPA), you wrap your DOM-updating code in a document.startViewTransition() call. The browser captures the 'before' state, executes your code to update the DOM, captures the 'after' state, and then generates a tree of pseudo-elements to perform a default cross-fade animation. You can customize this animation using standard CSS properties on these pseudo-elements. For Multi-Page Apps (MPAs), the process is similar but triggered automatically during navigation, if opted in.

When to use it

Use this API to create meaningful transitions that guide the user and reduce perceived latency. It's perfect for animating an element from a list view as it morphs into a detail view, smoothly switching between tabs, or creating seamless navigations between pages in an MPA. This helps users stay in context as the UI changes.

When not to use it

Avoid using view transitions for purely decorative animations that don't clarify a state change, as they can be distracting. Most importantly, do not build application logic that depends on the transition completing. It is a progressive enhancement; your application must function perfectly in browsers that don't support it, where the state change will simply happen instantly.

One canonical example

In an SPA, to animate a content swap, you simply wrap the update function: document.startViewTransition(() => { contentElement.innerHTML = newContent; });. The browser handles the fade between the old and new content. To animate a specific element between two pages (a 'shared element' transition), you give it the same unique view-transition-name CSS property in both the start and end states.