JavaScript Document startViewTransition() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method
Decorative image with the word STARTVIEWTRANSITION

Definition

document.startViewTransition() starts a same-document (SPA), document-scoped view transition and returns a ViewTransition object (MDN). You pass an update callback that changes the DOM after the browser snapshots the old view.

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call document.startViewTransition. Start with this line.

JavaScript
document.startViewTransition(updateCallback | options)
CallWhat it does
document.startViewTransition(updateCallback | options)Primary signature.
document.startViewTransition(...)Call with the arguments your case needs.

Built into the browser. Call startViewTransition(...) on document — no import required.

Library declarations
JavaScript
document.startViewTransition(updateCallback | options)

Parameters

ParameterDescription
updateCallbackOptional. Updates the DOM; returns a Promise (MDN)
options.updateOptional. Same as updateCallback (default null)
options.typesOptional. String tags for selective CSS/JS (default [])

Return Value

Return ValueDescription
*ViewTransition instance

JavaScript Examples

Example 1 — Feature-Detect and Fallback (MDN)

If the API is missing, update the DOM immediately with no animation.

JavaScript
const box = document.getElementById("box");

function update() {
  box.textContent = box.textContent === "Hello" ? "Updated" : "Hello";
}

function change() {
  if (!document.startViewTransition) {
    update(); // MDN fallback
    return;
  }
  document.startViewTransition(update);
}

document.querySelector("button").addEventListener("click", change);
Try It Yourself

How It Works

  1. Share one updater so supported and unsupported paths stay in sync.
  2. Detect the method before calling it (MDN).
  3. Fallback: call update() with no transition.
  4. Supported: wrap the same updater in startViewTransition.

Example 2 — Update Callback Returns a ViewTransition

The callback runs after the old-view snapshot; the return value is a ViewTransition.

JavaScript
const box = document.getElementById("box");

if (typeof document.startViewTransition === "function") {
  const transition = document.startViewTransition(() => {
    box.textContent = "Done";
  });
  console.log(transition); // ViewTransition
  transition.finished.then(() => console.log("finished"));
} else {
  box.textContent = "Done";
}
Try It Yourself

How It Works

  1. Call with a function that mutates the DOM (MDN updateCallback).
  2. Snapshot first — the API captures the old view before your update.
  3. Get ViewTransition back for lifecycle hooks like finished.
  4. Keep a fallback so older browsers still update.

Example 3 — options.types

MDN: pass an options object with update and optional types tags.

JavaScript
const box = document.getElementById("box");

function update() {
  box.textContent = "Slide";
}

if (!document.startViewTransition) {
  update();
} else {
  document.startViewTransition({
    update,
    types: ["slide"] // selective CSS/JS (MDN)
  });
}
Try It Yourself

How It Works

  1. Options form accepts update instead of a bare function (MDN).
  2. types tags the transition for selective styles or logic.
  3. Defaults: update is null, types is [] (MDN).
  4. Still detect first — older engines may only accept the callback form (or none).
Compatibility

Browser Support

Document.startViewTransition() is a browser View Transition API. MDN marks it Baseline 2025 Newly available (since October 2025). Older browsers may lack it — feature-detect and update the DOM immediately as a fallback.

✓ Baseline 2025 · Newly available

Document.startViewTransition()

Same-document SPA view transitions. Supported in the latest major browsers. Always detect before calling.

New Baseline 2025
Google Chrome Latest (Baseline 2025)
Yes
Microsoft Edge Latest (Baseline 2025)
Yes
Mozilla Firefox Latest (Baseline 2025)
Yes
Apple Safari Latest (Baseline 2025)
Yes
Opera Latest (Baseline 2025)
Yes
Internet Explorer No
No
startViewTransition() Newly available

Bottom line: Use with feature detection and a plain update fallback. See the MDN startViewTransition() reference.

Frequently Asked Questions

MDN: Document.startViewTransition() starts a new same-document (SPA), document-scoped view transition and returns a ViewTransition object to represent it.
No. MDN marks Document.startViewTransition() as Baseline Newly available (since October 2025). It is not Deprecated, Experimental, or Non-standard on the Document page. Always feature-detect for older browsers.
A ViewTransition object instance (MDN).
Optional function invoked to update the DOM during the SPA view transition. It returns a Promise. The callback runs after a snapshot of the current page; when the promise fulfills, the transition begins in the next frame. If it rejects, the transition is abandoned (MDN).
Document.startViewTransition() is document-scoped (whole-page same-document transitions). Element.startViewTransition() scopes the transition to one element’s subtree so the rest of the page can stay interactive (MDN).
Yes. Always feature-detect. If document.startViewTransition is missing, update the DOM immediately without animation (MDN basic usage pattern).

Next: write()

Continue with the Document write() method in the tutorial series.

write() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

20 people found this page helpful

JavaScript Document requestStorageAccessFor() Method JavaScript Document write() Method