web-view-transition

name: web-view-transition description: > Expert guidance for implementing the View Transition API — covering same-document (SPA) transitions with document.startViewTransition(), cross-document (MPA) transitions with @view-transition, customizing animations via CSS pseudo-elements (::view-transition-old, ::view-transition-new, ::view-transition-group), per-element animations with view-transition-name, JavaScript control via the ViewTransition promises (ready, finished, updateCallbackDone), context-aware transition types with :active-view-transition-type(), and graceful fallbacks for unsupported browsers. Use this skill when someone wants page transition animations, shared-element transitions, slide/fade/circular-reveal effects, or asks about startViewTransition, @view-transition, view-transition-name, ::view-transition-* pseudo-elements, or the ViewTransition object — even if they just say "smooth page transitions" or "animate between routes". license: MIT metadata: author: "Ikuma Yamashita" version: "1.0.0"

Web View Transition API

The View Transition API creates animated transitions between DOM states or page navigations with minimal code. The browser handles snapshotting old/new states and animating between them.

Browser support: Chrome 111+, Edge 111+, Firefox 144+, Safari 18+ (Baseline 2025). Always provide a no-animation fallback.

Quick mental model

When a transition fires, the browser:

1. Captures a static snapshot of the current view
2. Applies your DOM change
3. Captures a live snapshot of the new view
4. Animates old → new using a pseudo-element tree layered above the page

The pseudo-element tree looks like:

::view-transition
└─ ::view-transition-group(root)
   └─ ::view-transition-image-pair(root)
      ├─ ::view-transition-old(root)   ← static old snapshot
      └─ ::view-transition-new(root)   ← live new snapshot

Named elements get their own group alongside root.

SPA (same-document) transitions

Basic usage

Wrap your DOM update in document.startViewTransition(). The default cross-fade animation applies automatically.

function navigate(updateFn) {
  // Graceful fallback — the update still runs, just without animation
  if (!document.startViewTransition) {
    updateFn();
    return;
  }

  document.startViewTransition(updateFn);
}

The callback can be async; the transition waits for the returned promise.

document.startViewTransition(async () => {
  const data = await fetchNewContent();
  renderContent(data);
});

Animate specific elements separately

By default the whole page cross-fades. Assign view-transition-name to elements you want to animate independently. Names must be unique per frame.

/* CSS */
.hero-image {
  view-transition-name: hero;
}

nav {
  view-transition-name: site-nav;
}

This generates separate ::view-transition-group(hero) and ::view-transition-group(site-nav) branches. The browser automatically morphs position and size between old/new states for those elements.

Avoid conflicts: if two rendered elements share the same name, ready rejects and the transition is skipped. Assign names dynamically and clean them up:

document.startViewTransition(() => {
  clickedCard.style.viewTransitionName = "selected-card";
  updateDOM();
  // Reset in the next frame to prevent bfcache conflicts
  requestAnimationFrame(() => {
    clickedCard.style.viewTransitionName = "";
  });
});

MPA (cross-document) transitions

No JavaScript needed. Both the outgoing and destination pages must opt in with the CSS @view-transition at-rule. Both pages must be same-origin.

/* Add to CSS on BOTH pages */
@view-transition {
  navigation: auto;
}

That's it for a default cross-fade. Customize animations in the destination page's CSS.

Customizing animations

Target the pseudo-elements to override the default cross-fade. Prefer targeting ::view-transition-group() for duration/easing so the values cascade to old/new consistently.

/* Slow down all transitions */
::view-transition-group(root) {
  animation-duration: 0.4s;
  animation-timing-function: ease-in-out;
}

/* Custom swipe-up animation */
@keyframes slide-out {
  to {
    transform: translateY(-100%);
  }
}
@keyframes slide-in {
  from {
    transform: translateY(100%);
  }
}

::view-transition-old(root) {
  animation: 0.4s ease-in both slide-out;
}
::view-transition-new(root) {
  animation: 0.4s ease-in both slide-in;
}

Use * to target all named groups at once:

::view-transition-group(*) {
  animation-duration: 0.3s;
}

Circular-reveal (Web Animations API)

For programmatic animations that depend on runtime data (e.g. click position), use the ViewTransition.ready promise together with the Web Animations API.

let lastClick;
document.addEventListener("click", (e) => (lastClick = e));

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

  const x = lastClick?.clientX ?? innerWidth / 2;
  const y = lastClick?.clientY ?? innerHeight / 2;
  const r = Math.hypot(
    Math.max(x, innerWidth - x),
    Math.max(y, innerHeight - y),
  );

  const transition = document.startViewTransition(updateFn);

  transition.ready.then(() => {
    document.documentElement.animate(
      {
        clipPath: [
          `circle(0 at ${x}px ${y}px)`,
          `circle(${r}px at ${x}px ${y}px)`,
        ],
      },
      {
        duration: 500,
        easing: "ease-in",
        pseudoElement: "::view-transition-new(root)",
      },
    );
  });
}

// Required CSS to disable default cross-fade blending
// ::view-transition-image-pair(root) { isolation: auto; }
// ::view-transition-old(root), ::view-transition-new(root) {
//   animation: none; mix-blend-mode: normal; display: block;
// }

ViewTransition object (JavaScript control)

document.startViewTransition() returns a ViewTransition object. Access it in MPA transitions via PageSwapEvent.viewTransition (outgoing page) and PageRevealEvent.viewTransition (incoming page). Also available anywhere via document.activeViewTransition.

const transition = document.startViewTransition(updateFn);

// Know when the DOM is updated (regardless of animation outcome)
transition.updateCallbackDone.then(() => console.log("DOM updated"));

// Run custom JS animation at the right moment
transition.ready.then(() => {
  /* animate */
});

// Cleanup after animation completes
transition.finished.then(() => {
  element.style.viewTransitionName = "";
});

// Skip animation (DOM update still runs)
transition.skipTransition();

Back/forward direction pattern

async function handleNav(isBack) {
  if (isBack) document.documentElement.classList.add("back-nav");

  const transition = document.startViewTransition(updateFn);

  try {
    await transition.finished;
  } finally {
    document.documentElement.classList.remove("back-nav");
  }
}

.back-nav::view-transition-old(root) {
  animation-name: slide-out-right;
}
.back-nav::view-transition-new(root) {
  animation-name: slide-in-left;
}

Transition types (context-aware animations)

Types let you apply different animations to the same elements depending on context (e.g. "forwards" vs "backwards" in a gallery).

SPA — pass types to startViewTransition

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

Modify types dynamically on the returned object:

const vt = document.startViewTransition({ update: renderFn });
if (isBack) vt.types.add("backwards");

MPA — set types in @view-transition

@view-transition {
  navigation: auto;
  types: chapter-forward;
}

Or assign dynamically via pageswap/pagereveal events:

window.addEventListener("pageswap", (e) => {
  if (e.viewTransition && goingForward(e)) {
    e.viewTransition.types.add("forwards");
  }
});

Apply CSS per type

/* Styles when any transition is active */
html:active-view-transition {
  :root {
    view-transition-name: none;
  }
  .card {
    view-transition-name: card;
  }
}

/* Different animations per type */
html:active-view-transition-type(forwards) {
  &::view-transition-old(card) {
    animation-name: slide-out-left;
  }
  &::view-transition-new(card) {
    animation-name: slide-in-right;
  }
}

html:active-view-transition-type(backwards) {
  &::view-transition-old(card) {
    animation-name: slide-out-right;
  }
  &::view-transition-new(card) {
    animation-name: slide-in-left;
  }
}

MPA: pageswap / pagereveal pattern

Use these events to set view-transition-name dynamically on MPA pages, enabling shared-element transitions between specific elements.

// outgoing page — runs just before unload
window.addEventListener("pageswap", async (e) => {
  if (!e.viewTransition) return;

  const targetUrl = new URL(e.activation.entry.url);
  if (isDetailPage(targetUrl)) {
    const id = extractId(targetUrl);
    document.querySelector(`#item-${id} img`).style.viewTransitionName =
      "hero-img";

    // Clean up to avoid bfcache naming conflicts
    await e.viewTransition.finished;
    document.querySelector(`#item-${id} img`).style.viewTransitionName = "";
  }
});

// incoming page — runs when new page first renders
window.addEventListener("pagereveal", async (e) => {
  if (!e.viewTransition) return;

  const fromUrl = navigation.activation.from?.url;
  if (fromUrl && isListPage(new URL(fromUrl))) {
    document.querySelector(".detail-hero").style.viewTransitionName =
      "hero-img";

    await e.viewTransition.finished;
    document.querySelector(".detail-hero").style.viewTransitionName = "";
  }
});

Common pitfalls

Duplicate view-transition-name: if two visible elements share a name, ViewTransition.ready rejects and the transition is skipped silently. Clean up names after transitions using finished.

bfcache conflicts: when the back button is pressed, the page is restored from cache. If names were left set, the next pagereveal handler sets them again → duplicate → skipped. Always remove names after finished.

Hidden page skips transition: if the page is not visible (minimized, other tab), startViewTransition skips the animation automatically. This is correct behavior — the DOM update still runs.

MPA cross-origin: cross-document transitions only work between same-origin pages. A cross-origin redirect in the chain also disables the activation property (PageSwapEvent.activation returns null).

match-element keyword: you can use view-transition-name: match-element to automatically assign unique names to all matched elements, useful for list items without manual ID assignment.

Accessibility

Respect the user's motion preference. When prefers-reduced-motion: reduce is set, either remove the animation or make it instant.

@media (prefers-reduced-motion: reduce) {
  ::view-transition-group(*),
  ::view-transition-old(*),
  ::view-transition-new(*) {
    animation-duration: 0.01ms !important;
  }
}

Reference files

Read these when you need deeper detail than what is covered above.

• references/api.md — Complete API reference: browser support table, Document.startViewTransition() signature, all ViewTransition promises, ViewTransitionTypeSet methods, pageswap/pagereveal event objects, and every CSS addition (@view-transition, view-transition-name, view-transition-class, pseudo-classes, pseudo-elements, <link rel="expect">)
• references/using.md — Detailed walkthrough: how the transition process works step-by-step, SPA and MPA setup, CSS animation customization, per-element naming, the circular-reveal Web Animations API pattern, back/forward direction patterns, pageswap/pagereveal shared-element examples, and MPA render stabilization with <link rel="expect">
• references/using-types.md — In-depth guide to transition types: SPA types option, ViewTransition.types.add(), type-specific CSS with :active-view-transition-type(), static MPA types in @view-transition, and dynamic MPA types via pageswap/pagereveal with direction detection