Document: startViewTransition() method

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

The startViewTransition() method of the Document interface starts a new same-document (SPA) view transition and returns a ViewTransition object to represent it.

When startViewTransition() is invoked, a sequence of steps is followed as explained in The view transition process.

Syntax

js
startViewTransition()
startViewTransition(updateCallback)

Parameters

updateCallback Optional

An optional callback function typically invoked to update the DOM 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.

Return value

A ViewTransition object instance.

Examples

Basic usage

In our Basic SPA View Transitions demo, the updateView() function handles both browsers that do and don't support the View Transition API. In supporting browsers, we invoke startViewTransition() to trigger the view transition process without worrying about the return value.

js
function updateView(event) {
  // Handle the difference in whether the event is fired on the <a> or the <img>
  let targetIdentifier;
  if (event.target.firstChild === null) {
    targetIdentifier = event.target;
  } else {
    targetIdentifier = event.target.firstChild;
  }

  const displayNewImage = () => {
    const mainSrc = `${targetIdentifier.src.split("_th.jpg")[0]}.jpg`;
    galleryImg.src = mainSrc;
    galleryCaption.textContent = targetIdentifier.alt;
  };

  // Fallback for browsers that don't support View Transitions:
  if (!document.startViewTransition) {
    displayNewImage();
    return;
  }

  // With View Transitions:
  const transition = document.startViewTransition(() => displayNewImage());
}

Specifications

Specification
CSS View Transitions Module Level 1
# dom-document-startviewtransition

Browser compatibility

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
startViewTransition

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
See implementation notes.

See also