# View Transition

> document.startViewTransition() animates DOM state changes. This reference covers lifecycle promises, named elements, failure handling, and fallbacks.

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.

## Browser support

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](/compatibility/api/) alongside runtime detection when older browser versions remain in your support range.

## Syntax

```js
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.

## Members

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.

## Exceptions

`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.

:::caution
The Level 1 specification requires each rendered element participating in the named capture to have a unique `view-transition-name`. If more than one rendered element has the same name while the old or new state is captured, `ready` rejects with `InvalidStateError`; the update callback still runs, and `finished` still fulfills after the end state is reached ([capturing the old state](https://www.w3.org/TR/css-view-transitions-1/#capture-the-old-state), W3C).
:::

## Examples

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.

### Switching panels with a working fallback

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()`.

```html
<!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.

### Recovering when a named transition fails

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.

```js
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.

## See also

- [Navigation API](/reference/capabilities/navigation-api/), for intercepting and managing same-document navigation
- [User activation](/reference/capabilities/user-activation/), for APIs whose calls are tied to user gestures
- [CSS View Transitions Module Level 1](https://www.w3.org/TR/css-view-transitions-1/) (W3C)
- [Same-document view transitions for single-page applications](https://developer.chrome.com/docs/web-platform/view-transitions/same-document) (Chrome for Developers)
- [WebKit Features in Safari 18.0](https://webkit.org/blog/15865/webkit-features-in-safari-18-0/) (WebKit)