JavaScript Element startViewTransition() Method

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

Definition

Element.startViewTransition() starts a same-document (SPA) element-scoped view transition and returns a ViewTransition object (MDN). DOM updates in the callback animate only inside that element’s subtree — the rest of the page stays interactive.

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

Syntax

Call el.startViewTransition. Start with this line.

JavaScript
element.startViewTransition()
CallWhat it does
element.startViewTransition()Primary signature.
el.startViewTransition(...)Call with the arguments your case needs.

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

Library declarations
JavaScript
element.startViewTransition()

Parameters

ParameterDescription
updateCallbackOptional. Update the element’s DOM; may return a Promise
options.updateOptional. Same callback via an options object
options.typesOptional. String tags for selective CSS/JS (default [])

Return Value

Return ValueDescription
*ViewTransition instance

JavaScript Examples

Example 1 — Basic Toggle (MDN)

Wrap a simple DOM update in startViewTransition.

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

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

slide.startViewTransition(() => {
  updateSlide();
});
Try It Yourself

How It Works

  1. Pick the root element. The transition is scoped to its subtree.
  2. Pass an update callback. Change only that element’s content.
  3. API snapshots, then updates. Old and new states animate (MDN).
  4. Returns ViewTransition. You can await finished if needed.

Example 2 — Feature Detect (MDN)

Fall back to a plain update when the method is missing.

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

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

function handleClick() {
  if (typeof slide.startViewTransition !== "function") {
    updateSlide(); // no animation, still works
    return;
  }
  slide.startViewTransition(() => updateSlide());
}
Try It Yourself

How It Works

  1. Detect the method. Limited / Experimental — not everywhere yet.
  2. Fallback path. Same DOM update, no animation.
  3. Supported path. Callback runs inside the transition (MDN).
  4. UX tip. Content still updates in older browsers.

Example 3 — options.types

Tag the transition so CSS/JS can react selectively (MDN).

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

const vt = slide.startViewTransition({
  update() {
    slide.textContent = "Slide 2";
  },
  types: ["slide-next"]
});

console.log(vt); // ViewTransition
// CSS can target ::view-transition-* for type "slide-next"
Try It Yourself

How It Works

  1. Pass an options object. update is the DOM callback.
  2. Set types. Labels this transition (default []).
  3. Use types in CSS/JS for different animation styles (MDN).
  4. Keep a reference to the returned ViewTransition if you need it.
Compatibility

Browser Support

Element.startViewTransition() is Experimental with Limited availability on MDN (not Baseline). Feature-detect and provide an instant DOM-update fallback.

✓ Experimental · Limited

Element.startViewTransition()

Element-scoped View Transitions — growing support, not universal yet.

— Limited
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Android WebView Supported · Modern WebView
Full support
startViewTransition() Limited

Bottom line: Detect typeof el.startViewTransition === "function". Prefer element scope for local widgets; use document.startViewTransition for full-page SPA transitions.

Frequently Asked Questions

It starts a same-document (SPA) element-scoped view transition on an element's DOM subtree and returns a ViewTransition object (MDN). DOM updates inside the callback animate only within that element's scope.
MDN marks Element.startViewTransition() as Experimental and Limited availability (not Baseline). It is not Deprecated or Non-standard.
A ViewTransition object instance representing the transition (MDN).
Optional function that updates the element's DOM during the transition. It may return a Promise; the transition begins when that promise fulfills. If it rejects, the transition is abandoned (MDN).
Document.startViewTransition() is document-scoped and makes the whole page non-interactive during the transition. Element.startViewTransition() scopes the transition to one element's subtree — the rest of the page stays interactive (MDN).
An optional array of strings naming the transition types, so you can apply selective CSS or JS based on which transition is running (MDN). Defaults to an empty array.

Next: toggleAttribute()

Learn how to add or remove a boolean attribute in one call.

toggleAttribute tutorial →

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)

12 people found this page helpful

JavaScript Element activeViewTransition Property JavaScript Element toggleAttribute() Method