JavaScript Element startViewTransition() Method

What You’ll Learn

Element.startViewTransition() is an instance method that starts an element-scoped view transition on a DOM subtree and returns a ViewTransition object. Learn MDN’s slideshow demo, the updateCallback and options.types parameters, how it differs from document.startViewTransition(), pairing with activeViewTransition, and five try-it labs aligned with MDN.

Introduction

View transitions animate DOM updates smoothly instead of swapping content instantly. You may already know document.startViewTransition(), which scopes a transition to the entire page. element.startViewTransition() scopes it to one element’s subtree (MDN).

That means only the scoped region becomes non-interactive during the animation; the rest of the page keeps working. You can run multiple element-scoped transitions at once, and clipped overflow content stays clipped (MDN).

This page is part of JavaScript Element. Read activeViewTransition to inspect an in-flight transition without storing the return value.

Understanding the startViewTransition() Method

Calling el.startViewTransition(updateCallback) creates a view transition rooted on el. Only DOM changes inside that element’s subtree are animated (MDN).

• It is an instance method on Element.
• Returns a ViewTransition object instance (MDN).
• updateCallback (optional) — updates DOM during the transition; may return a Promise (MDN).
• options.update — same as updateCallback when using the options object form (MDN).
• options.types — array of transition type strings for selective CSS/JS styling (MDN).
• If the callback’s Promise rejects, the transition is abandoned (MDN).
• Pseudo-elements like ::view-transition-group(root) are placed inside the transition root (MDN).

📝 Syntax

General form of Element.startViewTransition (MDN):

startViewTransition()
startViewTransition(updateCallback)
startViewTransition(options)

Parameters

• updateCallback (optional) — function that updates the element’s DOM; may return a Promise (MDN).
• options.update (optional) — same callback when using the options object (MDN).
• options.types (optional) — array of strings for view transition types; defaults to [] (MDN).

Return value

A ViewTransition object instance (MDN).

Common patterns

const slide = document.querySelector("section");

function updateSlide() {
  slide.textContent = slide.textContent === "Slide 1" ? "Slide 2" : "Slide 1";
  slide.style.backgroundColor =
    slide.textContent === "Slide 1" ? "green" : "orange";
}

function handleClick() {
  if (!slide.startViewTransition) {
    updateSlide();
    return;
  }
  slide.startViewTransition(() => updateSlide());
}

// Options form with types (MDN)
slide.startViewTransition({
  update: () => updateSlide(),
  types: ["slide-change"]
});

Examples Gallery

Examples follow MDN Element.startViewTransition() patterns. Use View Output or Try It Yourself for each case. Feature-detect before use.

const slide = document.querySelector("section");
const btn = document.querySelector("button");

function updateSlide() {
  if (slide.textContent === "Slide 1") {
    slide.textContent = "Slide 2";
    slide.style.backgroundColor = "orange";
  } else {
    slide.textContent = "Slide 1";
    slide.style.backgroundColor = "green";
  }
}

function handleClick() {
  if (!slide.startViewTransition) {
    updateSlide();
    return;
  }
  slide.startViewTransition(() => updateSlide());
}

btn.addEventListener("click", handleClick);

Slide toggles with animated cross-fade (supporting browsers).

function runUpdate(el, updateFn) {
  if (typeof el.startViewTransition === "function") {
    return el.startViewTransition(updateFn);
  }
  updateFn();
  return null;
}

runUpdate(card, () => {
  card.classList.toggle("expanded");
});

Update runs in all browsers; animation only when supported.

const panel = document.getElementById("panel");

const transition = panel.startViewTransition(() => {
  panel.hidden = !panel.hidden;
});

transition.finished.then(() => {
  console.log("element transition finished");
});

element transition finished

const widget = document.getElementById("widget");

widget.startViewTransition(async () => {
  const data = await fetch("/api/widget").then(r => r.json());
  widget.textContent = data.title;
  // Transition begins after this promise fulfills (MDN)
});

Animates after async data loads; abandoned if promise rejects (MDN).

const card = document.getElementById("card");

card.startViewTransition({
  update: () => card.classList.toggle("flipped"),
  types: ["flip", "card-update"]  // MDN: defaults to []
});

types: ["flip", "card-update"] applied to transition.

🚀 Common Use Cases

• Image or content slideshows inside a card (MDN demo).
• Expanding/collapsing panels without freezing the whole page.
• Tab panels and widget state changes in SPAs.
• Multiple simultaneous transitions on different components (MDN).
• Clipped carousel or overflow-hidden galleries (MDN).
• Progressive enhancement with instant-update fallback (MDN).

📝 Notes

• Experimental and Limited availability on MDN — experimental banner shown above.
• Not Deprecated or Non-standard (CSS View Transitions Module Level 2).
• Only DOM updates inside the calling element’s subtree transition (MDN).
• Rejects in the callback abandon the transition (MDN).
• Pair with activeViewTransition to read in-flight transitions.
• Related: activeViewTransition, document.startViewTransition(), scroll(), JavaScript hub.

💡 Best Practices