Skip to content

API in Capabilities

View Transition

Published

The View Transition API captures a document before and after a DOM change, then presents the captures in a pseudo-element tree that CSS animations can style. document.startViewTransition(updateCallback) starts a same-document transition and returns a ViewTransition whose promises expose the update and animation stages.

BCD api.Document.startViewTransition and api.ViewTransition record support from Chrome 111, Firefox 144, and Safari 18, with the corresponding mobile and Chromium-derived browser entries mirrored from those engines. Firefox 144 release notes describe support for single-page applications, while Safari 18 release notes describe the Level 1 API. Check the broader API compatibility data alongside runtime detection when older browser versions remain in your support range.

const transition = document.startViewTransition(updateCallback)
const transition = document.startViewTransition({ update, types })
await transition.updateCallbackDone
await transition.ready
await transition.finished
transition.skipTransition()

Level 1 defines the callback form. The callback runs asynchronously after the browser captures the old state; its DOM changes establish the new state. Level 2 adds an options dictionary whose update member supplies that callback and whose types member assigns transition types. The method returns immediately, before the callback or animation completes.

The returned object separates the DOM update from preparation of the visual transition and completion of its animations.

Member Type Meaning
updateCallbackDone Promise<undefined> Fulfills when the update callback fulfills and rejects with the callback’s rejection reason.
ready Promise<undefined> Fulfills after the transition pseudo-elements are created and before their animations start. It rejects when the transition cannot begin.
finished Promise<undefined> Fulfills when the end state is visible and interactive. It rejects only when the update callback rejects.
skipTransition() method Skips or finishes the visual transition without preventing the update callback from running.

The browser captures the old state, pauses rendering, runs the update callback, captures the new state, creates the ::view-transition pseudo-element tree, and runs its CSS animations. The default transition is a page-wide cross-fade. Assign the same unique view-transition-name to the old and new forms of an element when that element needs its own capture. Style ::view-transition-old(name) and ::view-transition-new(name) with CSS animations to control the outgoing and incoming captures.

updateCallbackDone is the promise to await when later application work depends on the DOM update itself. Await ready before starting a Web Animations API animation against the generated pseudo-elements. Await finished when work must follow the point at which the new state is visible and interactive. Calling skipTransition() still lets updateCallbackDone reflect the callback result and lets the application reach the new state.

startViewTransition() returns a ViewTransition; the lifecycle promises report failures asynchronously. The specification defines the following paths.

Promise Failure condition
updateCallbackDone The update callback throws or returns a rejected promise.
ready The callback rejects, the document is hidden, another condition prevents capture, or two rendered elements use the same view-transition-name.
finished The update callback rejects. A skipped visual transition otherwise reaches the end state and fulfills.

Starting a transition while the document’s visibility state is hidden skips it with InvalidStateError. Starting another transition while one is active skips the earlier transition with AbortError; both asynchronous callbacks can still run. Application code that must serialize state changes therefore needs its own queue or cancellation mechanism.

Treat the animation as an enhancement around a state change. Each example performs the same DOM update when the API is absent, so the button or selected view remains usable without transition support.

This complete document changes the selected panel after a button click. The fallback calls selectPanel() directly; a supporting browser wraps the same call in startViewTransition().

<!doctype html>
<html lang="en">
<meta charset="utf-8" />
<title>Panel transition</title>
<button id="switch" type="button">Show details</button>
<main id="panel">Summary</main>
<script>
const button = document.querySelector("#switch");
const panel = document.querySelector("#panel");
function selectPanel() {
panel.textContent = "Details";
button.disabled = true;
}
button.addEventListener("click", () => {
if (!("startViewTransition" in document)) {
selectPanel();
return;
}
document.startViewTransition(selectPanel);
});
</script>
</html>

The expected end state is the text Details and a disabled button in either branch. In a supporting browser, the default page-wide cross-fade surrounds the change. If no animation appears, confirm that the click still produces that end state before inspecting animation rules.

Two visible cards with the same view-transition-name make ready reject. This example prevents that failure by assigning a unique name from each card’s data-id, handles a rejected update, and reports a skipped animation without undoing a successful DOM change.

const status = document.querySelector("#status");
const cards = [...document.querySelectorAll(".card")];
function assignUniqueNames() {
for (const card of cards) {
card.style.viewTransitionName = `card-${card.dataset.id}`;
}
}
async function reorderCards() {
assignUniqueNames();
if (!("startViewTransition" in document)) {
cards[0].parentNode.append(...[...cards].reverse());
status.textContent = "Reordered without animation";
return;
}
const transition = document.startViewTransition(() => {
cards[0].parentNode.append(...[...cards].reverse());
});
transition.updateCallbackDone.catch((error) => {
status.textContent = `Update failed: ${error.name}`;
});
transition.ready.catch((error) => {
status.textContent = `Animation skipped: ${error.name}`;
});
await transition.finished.catch(() => {});
}

Give every .card a distinct data-id. If ready reports InvalidStateError, inspect the computed view-transition-name values for duplicates. If updateCallbackDone rejects, repair the callback first because finished rejects with the same callback failure; a ready rejection by itself means the DOM update can still have succeeded.

Specifications

SpecificationStatus
CSS View Transitions Module Level 1: APIW3C
CSS View Transitions Module Level 2Other