JavaScript Document activeViewTransition Property

What You’ll Learn

Document.activeViewTransition is a read-only instance property that returns the ViewTransition currently active on the document, or null if none is running. Learn why MDN recommends it over saving references, how it pairs with document.startViewTransition(), cross-document pagereveal / pageswap access, and five hands-on examples.

Introduction

The View Transition API animates DOM updates smoothly. With document-scoped transitions you call document.startViewTransition(callback) to capture the old page state, run your DOM update, then animate to the new state.

Sometimes you start a transition in one place and need the same ViewTransition object elsewhere—to await finished, call skipTransition(), or check whether a transition is still running. MDN: document.activeViewTransition gives a consistent way to read the active transition without storing the return value yourself.

console.log(document.activeViewTransition); // null when idle (if supported)

Related Document tutorials: activeElement, Document constructor. Compare with element-scoped Element.activeViewTransition.

Understanding the Property

MDN: the activeViewTransition read-only property of the Document interface returns a ViewTransition instance representing the view transition currently active on the document.

• Read-only — you read it; you do not assign to it.
• Value — ViewTransition while active, otherwise null.
• Experimental — Limited availability (not Baseline) on MDN.
• Pair with — document.startViewTransition() for same-document transitions.
• Cross-document — also reachable while a navigation transition runs (via page events or this property).

📝 Syntax

document.activeViewTransition

Value

A ViewTransition, or null if the document has no active view transition.

MDN pattern

document.startViewTransition(() => {
  updateUI();
});

if (document.activeViewTransition) {
  console.log("A view transition is currently active");
}

document.activeViewTransition.finished.then(() => {
  console.log("View transition finished");
});

⚖️ Document vs Element scope

Document-scoped transitions are common for SPA route changes and full-page UI swaps. Element-scoped transitions suit cards and widgets that animate without freezing the entire page. Detect each API separately—support can differ.

Examples Gallery

Examples follow MDN Document: activeViewTransition. Labs feature-detect first. Real animations need a supporting browser and document.startViewTransition.

console.log({
  hasActiveViewTransition: "activeViewTransition" in Document.prototype,
  hasStartViewTransition: typeof document.startViewTransition === "function",
  tip: "Document.activeViewTransition is experimental — feature-detect first."
});

{
  "hasActiveViewTransition": true,
  "hasStartViewTransition": true,
  "tip": "Document.activeViewTransition is experimental — feature-detect first."
}

if (!("activeViewTransition" in document)) {
  console.log("activeViewTransition not supported");
} else {
  console.log({
    activeViewTransition: document.activeViewTransition,
    note: "null means no document-scoped transition is active"
  });
}

{
  "activeViewTransition": null,
  "note": "null means no document-scoped transition is active"
}

function updateUI() {
  heading.textContent = heading.textContent === "Hello" ? "Goodbye" : "Hello";
}

if (typeof document.startViewTransition !== "function") {
  updateUI();
  console.log("No View Transition API — instant update");
} else {
  document.startViewTransition(updateUI);

  if (document.activeViewTransition) {
    console.log("A view transition is currently active");
    document.activeViewTransition.finished.then(() => {
      console.log("View transition finished");
    });
  }
}

A view transition is currently active
View transition finished

if (typeof document.startViewTransition !== "function") {
  console.log("Cannot compare — startViewTransition missing");
} else {
  const vt = document.startViewTransition(() => {
    panel.dataset.state = panel.dataset.state === "a" ? "b" : "a";
  });
  console.log({
    sameReference: document.activeViewTransition === vt,
    tip: "Store vt or re-read activeViewTransition later"
  });
}

{
  "sameReference": true,
  "tip": "Store vt or re-read activeViewTransition later"
}

console.log({
  documentProp: "activeViewTransition" in Document.prototype,
  documentStart: typeof document.startViewTransition,
  documentActiveNow: document.activeViewTransition ?? null,
  elementProp: "activeViewTransition" in Element.prototype,
  elementStart: typeof Element.prototype.startViewTransition,
  status: "Document.activeViewTransition is experimental (document-scoped VT)"
});

{
  "documentProp": true,
  "documentStart": "function",
  "documentActiveNow": null,
  "elementProp": true,
  "elementStart": "function",
  "status": "Document.activeViewTransition is experimental (document-scoped VT)"
}

🚀 Common Use Cases

• SPA route changes — await finished before focusing new content.
• Skip or cancel an in-flight page transition from a global handler.
• Guard UI actions while document.activeViewTransition != null.
• Cross-document navigations — read alongside pagereveal.viewTransition.
• Teaching document-scoped vs element-scoped View Transitions.
• Debugging whether the page still has an active transition.

🔧 How It Works

📝 Notes

• Experimental and Limited availability (MDN)—experimental banner shown above.
• Not Deprecated or Non-standard on MDN.
• Read-only; value is ViewTransition or null.
• Different from element.activeViewTransition (element scope).
• Also accessible via pagereveal / pageswap event viewTransition for cross-document cases.
• Related: activeElement, Element.activeViewTransition, Element.startViewTransition(), JavaScript hub.

💡 Best Practices