Tutorials

View Transitions API: animate layout changes and page navigations

A practical View Transitions API guide: startViewTransition with a fallback, shared element morphs, custom timing, cross-document transitions and pitfalls.

· 7 min read

Animating a layout change used to mean measuring elements before and after, then running a FLIP animation by hand or pulling in a library. The View Transitions API moves that work into the browser. You tell it when the DOM is about to change, it takes a snapshot before and after, and it animates between the two.

This guide covers the same-document API with a safe fallback, shared element morphs with view-transition-name, how to change duration and easing with the ::view-transition-* pseudo-elements, cross-document transitions for multi-page sites, and the pitfalls that make a transition silently skip.

  • Onboarding
  • Billing
  • Reports
  • Settings
  • Team
  • Exports
Switch layout or shuffle. Browsers without the API just swap instantly

How a view transition works

A view transition has four steps, and knowing them makes every other part of the API easier to reason about.

  1. Capture the old state. The browser takes a snapshot of the page, plus a separate snapshot of every element that has a view-transition-name.
  2. Run your update. Your callback changes the DOM. Rendering is paused while it runs, so the user never sees a half-updated page.
  3. Capture the new state. The browser snapshots the same named elements again, now in their new positions and sizes.
  4. Animate. It builds a tree of pseudo-elements over the page and animates from old to new. When the animations finish, the pseudo-elements are removed and the real DOM shows through.

The animation runs on images of the elements, not on the elements themselves. That is why a view transition can morph between two layouts that have nothing in common in the DOM, and also why the page is not interactive while it plays.

Same-document transitions with a fallback

For a single-page app, or any in-page change, wrap the DOM update in document.startViewTransition(). Always check that the method exists first, so older browsers still get the update, just without the animation.

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

layoutButton.addEventListener('click', () => {
  withTransition(() => {
    gallery.classList.toggle('is-list');
  });
});

The callback can be async. If you fetch data before rendering, return the promise, and the browser waits for it before taking the new snapshot. Keep that wait short: the page is frozen on the old snapshot until the promise settles.

startViewTransition() returns a ViewTransition object with three promises and one method:

With no other CSS, you get a cross-fade of the whole page. That is the root transition, and it is often too subtle to notice. The interesting part starts when you name elements.

Shared element morphs with view-transition-name

Give an element a view-transition-name and the browser tracks it separately. If an element with the same name exists before and after the update, it animates its position and size from one to the other. The elements do not need to be the same DOM node.

The classic case is a list card that grows into a detail view. The thumbnail in the card and the hero image on the detail view are different elements, but if both carry the same name at the right moment, the image appears to fly into place.

async function openDetail(card, item) {
  const thumb = card.querySelector('.thumb');

  if (!document.startViewTransition) {
    renderDetail(item);
    return;
  }

  // name the thumbnail only for the old snapshot
  thumb.style.viewTransitionName = 'hero-image';

  const transition = document.startViewTransition(() => {
    thumb.style.viewTransitionName = '';
    renderDetail(item); // renders <img class="detail-hero"> with the same name
  });

  await transition.finished;
}
.detail-hero { view-transition-name: hero-image; }

Setting the name in JavaScript, just before the transition, is the reliable pattern for lists. If every card in a list had the name hero-image in the stylesheet, the transition would fail, because names have to be unique. In the demo above each card has its own name (vtg-c1 to vtg-c6), which is why each one moves independently when you shuffle.

Customising duration and easing

During the animation the browser builds this pseudo-element tree on top of the page:

::view-transition
└─ ::view-transition-group(hero-image)
   └─ ::view-transition-image-pair(hero-image)
      ├─ ::view-transition-old(hero-image)
      └─ ::view-transition-new(hero-image)

Each part has a job. The group animates position and size from the old box to the new one. The old and new images cross-fade inside it. All of them are ordinary CSS animations, so you style them with ordinary animation properties.

/* every group, including root */
::view-transition-group(*) {
  animation-duration: 420ms;
  animation-timing-function: cubic-bezier(.2, .8, .2, 1);
}

/* one named element */
::view-transition-group(hero-image) {
  animation-duration: 550ms;
}

/* replace the default cross-fade on the page */
::view-transition-old(root) {
  animation: 200ms ease-in both vt-fade-out;
}
::view-transition-new(root) {
  animation: 300ms cubic-bezier(.2, .8, .2, 1) 100ms both vt-slide-in;
}

@keyframes vt-fade-out { to { opacity: 0; } }
@keyframes vt-slide-in { from { opacity: 0; transform: translateY(12px); } }

The default is 250 ms with ease, which feels short for anything that travels far. Somewhere between 350 and 500 ms with a strong ease-out works well for layout changes. If you want a slight settle at the end, a linear() spring on the group is a nice touch; the easing functions guide explains how to pick a curve.

PartPropertyDurationDelayEasing
Card group (demo)transform, width, height420 ms0cubic-bezier(.2, .8, .2, 1)
Card old imageopacity: 1 → 0420 ms0inherited from group
Card new imageopacity: 0 → 1420 ms0inherited from group
Root (page)cross-fade420 ms0cubic-bezier(.2, .8, .2, 1)

When the old and new snapshots have different aspect ratios, as in the grid to list switch, the images are stretched during the morph. For text-heavy elements that can look smeary. Two fixes: keep the animation short, or set height: 100% and object-fit on the old and new pseudo-elements so they crop instead of stretch.

Cross-document transitions for multi-page sites

A multi-page site can get the same effect on normal link navigations, without JavaScript. Both the outgoing and incoming page must opt in, and the navigation must be same-origin.

@view-transition {
  navigation: auto;
}

/* the same name on the listing page and the article page */
.post-card img { view-transition-name: var(--vt-name); }
.article-hero  { view-transition-name: var(--vt-name); }

Put the at-rule in a stylesheet that both pages load. Everything else works as on a single page: named elements morph, root cross-fades, and the same pseudo-elements take your custom timing. For a listing page, set the name per card (for example with an inline style="--vt-name: post-42") so only one card shares a name with the article you open.

Two events let you adjust things on the fly: pageswap fires on the old page just before it is replaced, and pagereveal fires on the new page before its first render. Both expose the active viewTransition, so you can set names or skip the transition based on where the user came from.

Browser support. Same-document transitions work in Chromium browsers, Safari and recent Firefox. Cross-document transitions arrived later and support is narrower. Check caniuse before you rely on either, and treat the animation as an enhancement: with the fallback above, unsupported browsers still get the correct content.

Pitfalls

Inspecting view transitions in DevTools

Because the pseudo-elements run ordinary CSS animations, the Chrome DevTools Animations panel records them. Open it from the command menu (Show Animations), trigger the transition, and you will see one row per pseudo-element with its duration, delay and easing. Set the playback speed to 10% to watch a morph frame by frame, or pause it and use the Elements panel to inspect the ::view-transition tree while it exists. The DevTools inspection guide covers the panel in more detail.

If the motion you want to match on another site is built with CSS keyframes, transitions, the Web Animations API, GSAP or Lottie, Capture Motion records it while it plays and exports the keyframes and easing as CSS, React or GSAP code, which you can then reuse for your own transition timing.

Summary

Wrap DOM updates in document.startViewTransition() behind a feature check. Name the elements that should morph, and keep each name unique at the moment of capture. Style ::view-transition-group(), ::view-transition-old() and ::view-transition-new() to set duration and easing. Add @view-transition { navigation: auto; } to both pages for multi-page sites. And switch the movement off for users who ask for reduced motion.

Questions

What does document.startViewTransition() do?

It takes a snapshot of the page, runs your callback to update the DOM, takes a second snapshot, and animates between the two. By default that animation is a cross-fade, and elements with a view-transition-name also move and resize.

Why is my view transition skipped?

The most common cause is two visible elements with the same view-transition-name at the same time. Names must be unique while the snapshots are taken, otherwise the browser aborts the transition and just applies the DOM change.

Do view transitions work across pages in a multi-page site?

Yes, for same-origin navigations in browsers that support cross-document view transitions. Add @view-transition { navigation: auto; } to the CSS of both the old and the new page. Other browsers simply navigate without the animation.

Can I copy the timing of a page transition I saw on another site?

You can inspect it in the Chrome DevTools Animations panel, which lists the animations on the view transition pseudo-elements. For motion built with CSS keyframes, transitions, the Web Animations API, GSAP or Lottie, Capture Motion records the keyframes, durations and easing and exports them as code.