JavaScript Document startViewTransition() Method

What You’ll Learn

document.startViewTransition() is an instance method that starts a same-document (SPA), document-scoped view transition and returns a ViewTransition object (see MDN Document: startViewTransition()). Learn the MDN color demo, updateCallback / options.types, CSS ::view-transition-group, how it compares to Element.startViewTransition(), and five try-it labs.

Introduction

Single-page apps often swap content with JavaScript. Without help, those updates feel abrupt. The View Transition API lets the browser snapshot the old UI, apply your DOM update, then animate to the new UI.

MDN: document.startViewTransition() starts a same-document, document-scoped transition and returns a ViewTransition you can await or skip. Pair it with CSS such as ::view-transition-group(root) to control timing and style.

Related tutorials: activeViewTransition, Element.startViewTransition(), getAnimations().

Understanding document.startViewTransition()

An instance method on Document (View Transition API).

• Job — start a same-document, document-scoped view transition (MDN).
• Returns — a ViewTransition object (MDN).
• updateCallback — optional DOM update function that returns a Promise (MDN).
• options — optional object with update and types (MDN).
• Reject path — if the callback promise rejects, the transition is abandoned (MDN).
• CSS — style with ::view-transition-group, ::view-transition-old, ::view-transition-new, and friends.
• Status — Baseline Newly available since October 2025; some parts may vary (MDN).

📝 Syntax

General forms of Document.startViewTransition (MDN):

startViewTransition()
startViewTransition(updateCallback)
startViewTransition(options)

Parameters

• updateCallback Optional — callback invoked to update the DOM during the SPA view transition process. It returns a Promise. Invoked once the API has taken a snapshot of the current page. When the promise fulfills, the view transition begins in the next frame. If it rejects, the transition is abandoned (MDN).
• options Optional — object that may include:
  • update — same as updateCallback; defaults to null (MDN).
  • types — array of strings applied as view transition types for selective CSS/JS; defaults to [] (MDN).

Return value

A ViewTransition object instance (MDN).

MDN basic pattern

const changeColor = () => {
  // Fallback for browsers that don't support View Transitions:
  if (!document.startViewTransition) {
    updateColor();
    return;
  }

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

⚖️ Document vs Element startViewTransition

Examples Gallery

Examples follow MDN Document: startViewTransition(). Always keep a non-animated fallback.

function applyUpdate(updateFn) {
  if (!document.startViewTransition) {
    updateFn();
    return null;
  }
  return document.startViewTransition(updateFn);
}

console.log("supported:", typeof document.startViewTransition === "function");

supported: true
(or false on older browsers)

const colors = ["darkred", "darkslateblue", "darkgreen"];
const colBlock = document.querySelector("section");
let count = 0;

const updateColor = () => {
  colBlock.style = `--bg: ${colors[count]}`;
  count = count !== colors.length - 1 ? ++count : 0;
};

const changeColor = () => {
  if (!document.startViewTransition) {
    updateColor();
    return;
  }
  document.startViewTransition(() => {
    updateColor();
  });
};

document.querySelector("#change-color").addEventListener("click", changeColor);

Section background animates between colors (or snaps instantly without API)

async function swapTitle(nextText) {
  const title = document.getElementById("title");
  const update = () => {
    title.textContent = nextText;
  };

  if (!document.startViewTransition) {
    update();
    console.log("updated without transition");
    return;
  }

  const transition = document.startViewTransition(update);
  await transition.finished;
  console.log("transition finished");
}

transition finished
(or updated without transition)

function goTheme(update) {
  if (!document.startViewTransition) {
    update();
    return;
  }

  document.startViewTransition({
    update,
    types: ["theme"],
  });
}

// CSS can target :active-view-transition-type(theme) where supported

Theme update runs (types support may vary by browser)

let current = null;

function navigate(update) {
  if (current) {
    current.skipTransition();
  }
  if (!document.startViewTransition) {
    update();
    current = null;
    return;
  }
  current = document.startViewTransition(update);
  current.finished.finally(() => {
    if (current && current.finished) current = null;
  });
}

Rapid clicks skip prior animation and apply the latest update

🚀 Common Use Cases

• SPA route / panel swaps — animate between same-document UI states (MDN).
• Theme or color changes — MDN color demo with CSS custom properties.
• Gallery / list updates — soften abrupt content replacement.
• Typed transitions — different CSS for “forward” vs “back” via types (MDN).
• Progressive enhancement — same updater with or without the API (MDN).
• Widget-scoped motion — prefer Element.startViewTransition() when only one region should animate.

📝 Notes

• MDN: Baseline Newly available since October 2025; some parts may vary.
• Not Deprecated, Experimental, or Non-standard on the Document method page.
• Always feature-detect and keep an instant DOM-update fallback (MDN).
• Document-scoped transitions differ from element-scoped ones (see Element tutorial).
• Style with view-transition pseudo-elements; duration often set on ::view-transition-group(root) (MDN).
• Related: activeViewTransition, Element.startViewTransition(), getAnimations().

💡 Best Practices