Skip to content
FEE
Frontend Engineering Essentials
Senior Level
Hardened· 2026-07

[FEE-11103] View Transitions — Level 1 ​

INFO

Declare a view-transition-name CSS property on an element, wrap a DOM mutation in document.startViewTransition(), and the browser captures a before screenshot, performs the swap, captures an after screenshot, and animates between them automatically. JavaScript no longer has to time the screenshot, the swap, and the animation start by hand.

Baseline Newly Available

Supported in Chrome 111+, Firefox 144+, Safari 18+. May not yet be safe for all production use without progressive enhancement.

Context ​

Single-page applications need to animate between views: a thumbnail click that should morph into a full-size hero image, or a route change that should slide the new view into place. Orchestrating this smoothly means running several asynchronous operations without letting them race.

The naive approach requires four synchronized steps:

  1. Capture a screenshot of the outgoing content.
  2. Start an animation on that screenshot so the old content appears to animate away.
  3. Swap the DOM to the new state.
  4. Animate the incoming content into its final position.

In practice, step 3 happens asynchronously: the new state may depend on a route change, a state update, or a React re-render. Steps 1 and 3 must be synchronized: if the DOM swaps before the screenshot is taken, the snapshot captures the wrong state. If the screenshot is taken too late, the user sees an unstyled flash before the animation begins.

Shared-element transitions compound the problem. When a thumbnail should "morph" into a hero image, the developer must:

  • Record the thumbnail's bounding box before the DOM update.
  • Record the hero image's bounding box after the DOM update.
  • Calculate the delta (position offset and scale change) between the two.
  • Apply a FLIP animation (First, Last, Invert, Play) using CSS transforms so the element appears to travel from the old position to the new one.
  • Ensure the element is composited correctly so it renders above both the outgoing and incoming content during the transition.

Existing libraries address parts of this problem. Framer Motion's AnimatePresence component handles mount/unmount animations but requires wrapping your component tree and pulling in a runtime dependency. The GSAP Flip plugin provides the position-delta calculation but requires learning a separate API and still relies on JavaScript to time the DOM swap correctly. Swup.js adds page transition orchestration, though it is built around full-page swaps and does not address component-level shared elements. Astro's <ClientRouter /> (formerly <ViewTransitions />) comes closest to the platform behavior described below: it wraps navigations in document.startViewTransition() automatically, but it is still a framework-specific router, not a browser primitive available to any stack.

The View Transition API addresses the root cause: the browser itself takes the before-snapshot, performs the DOM update atomically within the callback, takes the after-snapshot, and animates between them. The browser sequences the capture and the DOM swap itself, so JavaScript never has to time them.

The rest of this article builds toward one running example: a photo gallery single-page app. The gallery view shows a grid of thumbnails; clicking a thumbnail reveals a full-size detail view with the selected photo, and the thumbnail visually morphs into the hero image, scaling up and repositioning as the view changes.

The example must satisfy six requirements:

  • Transition from gallery to detail: thumbnail scales and moves to become the hero image.
  • Transition back: the reverse morph, hero image scales down and returns to thumbnail position.
  • No JavaScript FLIP calculation.
  • No third-party animation library.
  • Browsers without View Transition support receive an instant swap (graceful degradation).
  • Users with prefers-reduced-motion: reduce receive no animation.

With the View Transition API, both transitions reduce to a single document.startViewTransition() call and a view-transition-name CSS property on the shared element. The Visual section below lays out the pseudo-element tree the browser constructs to make this work, and the Example section builds the gallery end to end.

Visual ​

When a view transition runs, the browser builds a temporary pseudo-element tree on top of the document. Every named element (plus the page root, named root by default) gets its own branch:

::view-transition
  ::view-transition-group(root)
    ::view-transition-image-pair(root)
      ::view-transition-old(root)
      ::view-transition-new(root)
  ::view-transition-group(hero-photo)
    ::view-transition-image-pair(hero-photo)
      ::view-transition-old(hero-photo)
      ::view-transition-new(hero-photo)

::view-transition is the full-page overlay that sits above all document content. It is removed when the transition completes.

::view-transition-group(name) is a wrapper element that is positioned at the "before" bounds and animated to the "after" bounds. This is what produces the position and size morph for shared elements: the group itself translates and scales between the two bounding boxes.

::view-transition-image-pair(name) contains the two snapshot images and handles the cross-fade between them.

::view-transition-old(name) is the before-snapshot image. It fades out by default.

::view-transition-new(name) is the after-snapshot image. It fades in by default.

To customize the animation, target these pseudo-elements with @keyframes:

css
@keyframes slide-out-left {
  to { transform: translateX(-100%); opacity: 0; }
}
@keyframes slide-in-right {
  from { transform: translateX(100%); opacity: 0; }
}

::view-transition-old(root) {
  animation: slide-out-left 0.35s ease-in forwards;
}
::view-transition-new(root) {
  animation: slide-in-right 0.35s ease-out forwards;
}

Example ​

A photo gallery SPA where clicking a thumbnail transitions it into a full-size hero view using a shared-element morph animation.

html
<div class="gallery" id="gallery">
  <img class="thumb" src="photo-1.jpg" alt="Photo 1" onclick="showDetail(this)">
  <img class="thumb" src="photo-2.jpg" alt="Photo 2"
       onclick="showDetail(this)">
  <img class="thumb" src="photo-3.jpg" alt="Photo 3"
       onclick="showDetail(this)">
</div>
<div class="detail" id="detail" hidden>
  <img class="hero" id="hero-img" src="photo-1.jpg" alt=""
       style="view-transition-name: hero-photo">
  <button onclick="closeDetail()">Back to gallery</button>
</div>

Note: only the active thumbnail and the hero image share the hero-photo transition name. Only one of each is visible at any given time, ensuring there is no name collision.

css
.thumb {
  width: 150px;
  aspect-ratio: 1;
  object-fit: cover;
  cursor: pointer;
  border-radius: 4px;
}

.hero {
  width: 100%;
  max-width: 600px;
  aspect-ratio: 4 / 3;
  object-fit: cover;
  border-radius: 8px;
  display: block;
  margin: 0 auto;
}

/* The thumbnail is 1:1 and the hero is 4:3. The default snapshot sizing
   (inline-size: 100%; block-size: auto) keeps each snapshot's own aspect
   ratio, so as the group tweens between the square and 4:3 boxes the
   snapshot overflows or letterboxes the group -- a visible framing
   mismatch, not a warped photo. Setting height: 100%; width: auto instead
   makes each snapshot match the group's block size and cover on the
   inline axis; clipping the group hides the resulting inline overflow. */
::view-transition-old(hero-photo),
::view-transition-new(hero-photo) {
  height: 100%;
  width: auto;
}
::view-transition-group(hero-photo) {
  overflow: clip;
}

/* Customize the root transition duration */
::view-transition-old(root),
::view-transition-new(root) {
  animation-duration: 0.4s;
}

/* Disable all view transitions for users who prefer reduced motion */
@media (prefers-reduced-motion: reduce) {
  ::view-transition-old(*),
  ::view-transition-new(*),
  ::view-transition-group(*) {
    animation: none;
  }
}
js
function showDetail(thumb) {
  // Graceful degradation: instant swap for unsupported browsers
  if (!document.startViewTransition) {
    document.getElementById('gallery').hidden = true;
    document.getElementById('detail').hidden = false;
    return;
  }

  // Before the transition: assign the view-transition-name to the
  // clicked thumbnail so it participates in the shared-element morph
  thumb.style.viewTransitionName = 'hero-photo';

  document.startViewTransition(() => {
    // DOM mutations go inside the callback
    document.getElementById('gallery').hidden = true;
    document.getElementById('detail').hidden = false;

    // Update the hero image source to match the clicked thumbnail
    document.getElementById('hero-img').src = thumb.src;
    document.getElementById('hero-img').alt = thumb.alt;
  });

  // After the transition starts, remove the name from the thumbnail
  // so it does not conflict if the gallery is shown again
  thumb.style.viewTransitionName = '';
}

function closeDetail() {
  if (!document.startViewTransition) {
    document.getElementById('detail').hidden = true;
    document.getElementById('gallery').hidden = false;
    return;
  }

  document.startViewTransition(() => {
    document.getElementById('detail').hidden = true;
    document.getElementById('gallery').hidden = false;
  });
}

How the morph works ​

When showDetail() is called:

  1. The browser captures the "before" snapshot of hero-photo (the thumbnail at its small position) and the root (the full page).
  2. The callback runs: gallery is hidden, detail is shown, hero image source is updated.
  3. The browser captures the "after" snapshot of hero-photo (the hero image at its large position) and the root.
  4. ::view-transition-group(hero-photo) animates its position and size from the thumbnail bounds to the hero bounds.
  5. Inside the group, ::view-transition-old(hero-photo) (the thumbnail snapshot) cross-fades to ::view-transition-new(hero-photo) (the hero snapshot).
  6. Simultaneously, ::view-transition-old(root) (the gallery) fades out while ::view-transition-new(root) (the detail view) fades in.

Because the thumbnail is square and the hero image is 4:3, steps 4 and 5 tween boxes with different aspect ratios. The CSS comment above explains why: without the height: 100%; width: auto override, the snapshot keeps its own aspect ratio and overflows or letterboxes the tweened box, so overflow: clip on the group is needed to hide whatever no longer fits.

Customizing the hero morph animation ​

By default, the morph is a cross-fade combined with size/position interpolation. To make the image snap to full opacity immediately (showing only the size/position tween without any opacity change):

css
::view-transition-old(hero-photo) {
  animation: none;
  opacity: 0; /* hide the old snapshot immediately */
}
::view-transition-new(hero-photo) {
  animation: none;
  opacity: 1; /* show the new snapshot immediately */
}

With these rules, ::view-transition-group(hero-photo) still animates position and size, but the image inside it does not fade: it shows the new full-size image from the first frame and scales it from the hero size down to the thumbnail size, producing a zoom effect with no cross-fade.

Asymmetric enter and exit ​

For a slide-based page transition (enter from right, exit to left):

css
@keyframes slide-from-right {
  from {
    transform: translateX(30px);
    opacity: 0;
  }
}

@keyframes slide-to-left {
  to {
    transform: translateX(-30px);
    opacity: 0;
  }
}

::view-transition-old(root) {
  animation: slide-to-left 0.3s ease-in forwards;
}

::view-transition-new(root) {
  animation: slide-from-right 0.3s ease-out forwards;
}

@media (prefers-reduced-motion: reduce) {
  ::view-transition-old(*),
  ::view-transition-new(*),
  ::view-transition-group(*) {
    animation: none;
  }
}

Using the ViewTransition promise API ​

document.startViewTransition() returns a ViewTransition object with three promises:

js
const transition = document.startViewTransition(() => updateDOM());

// Resolves when the DOM update is complete and snapshots are taken
transition.updateCallbackDone.then(() => {
  console.log('DOM updated');
});

// Resolves when the pseudo-elements are created and the animation can begin
// Use this to cancel or skip the animation programmatically
transition.ready.then(() => {
  console.log('Animation starting');
});

// Resolves when the transition animation completes and pseudo-elements are removed
transition.finished.then(() => {
  console.log('Transition complete');
});

The ready promise is particularly useful for triggering Web Animations API animations on the pseudo-elements, for example to animate along a path or use a spring physics model that plain CSS cannot express.

Best Practices ​

  • MUST place all DOM mutations inside the startViewTransition callback. Mutations made before or after the call are not captured by the before/after snapshot machinery. The browser takes the "before" snapshot immediately before the callback runs and the "after" snapshot after the callback's returned promise resolves; any DOM change made outside this window is invisible to the transition system.

  • SHOULD give each shared element a unique view-transition-name. The property instructs the browser to treat the element as a named snapshot participant: it captures a separate before/after snapshot pair for that element and morphs it independently of the root cross-fade. If two elements that are simultaneously visible end up with the same view-transition-name, the browser aborts the entire transition and rejects the ViewTransition.ready promise with an InvalidStateError; the callback's DOM update still runs, but it lands as an instant swap with no animation. Names must be unique among all elements that are visible at snapshot time. A common mistake is applying the same name to every item in a list; catch the ready rejection during development to surface this early, and assign the name only to the specific element that participates in the current transition.

  • SHOULD always test with @media (prefers-reduced-motion: reduce) and disable or reduce the transition for users who have requested it. The browser's default cross-fade is subtle enough that some developers skip this, but custom keyframe animations applied to ::view-transition-old and ::view-transition-new may be severe enough to trigger vestibular symptoms. The recommended pattern is:

    css
    @media (prefers-reduced-motion: reduce) {
      ::view-transition-old(*),
      ::view-transition-new(*),
      ::view-transition-group(*) {
        animation: none;
      }
    }
  • SHOULD always provide a feature-detection fallback. document.startViewTransition is undefined on browsers that do not support the API. Check for it before calling:

    js
    if (!document.startViewTransition) {
      updateDOM(); // instant swap, no transition
      return;
    }
    document.startViewTransition(() => updateDOM());
  • MAY use contain: layout on shared elements to prevent layout side effects. A named view-transition element is promoted to its own compositing layer during the transition; applying contain: layout prevents it from affecting the layout of surrounding elements when it is moved or scaled.

  • MAY customize ::view-transition-old and ::view-transition-new independently to create asymmetric enter/exit animations. For example, the outgoing content can fade and slide up while the incoming content fades and slides in from below, using separate @keyframes targeting each pseudo-element.

  • SHOULD NOT assign view-transition-name dynamically to many elements at once. Each named element causes the browser to capture an additional GPU texture snapshot, so naming everything in a long list increases capture cost and can visibly delay the start of the transition. Assign the name only to the one element that participates in the current transition, and remove it afterward. When many elements genuinely need to animate as a group, use view-transition-class (Chrome 125+, Firefox 144+, Safari 18.2+) instead: give each element its own unique view-transition-name but share one class, then target ::view-transition-group(*.your-class) with a single rule instead of writing one selector per element.

Design Thinking ​

Why JS-orchestrated transitions were fragile ​

The fundamental problem is that JavaScript has no hook for "take a screenshot of the current paint right now." The closest approximation is html2canvas or element.getBoundingClientRect() before and after, but neither captures actual pixel content. Even if a screenshot were possible, the timing between "take screenshot," "start animation," "swap DOM," and "start incoming animation" must be coordinated through requestAnimationFrame, setTimeout, or transitionend events. Each of these hand-offs introduces a timing gap where a mid-swap state can flash to the user.

GSAP Flip solved part of this by recording element positions before and after a DOM update and computing the CSS transform delta automatically. But GSAP Flip still requires the developer to manually trigger the DOM change inside a GSAP-managed callback, and it animates the live element with CSS transforms; it does not capture a composited pixel snapshot, so the element's content stays live (not frozen) during the animation. If the element's content changes mid-transition, the animation shows the new content from frame 0 because there is no frozen snapshot to animate from.

How the browser's snapshot model eliminates the race ​

document.startViewTransition(callback) exposes a guaranteed ordering contract:

  1. The browser pauses rendering.
  2. It captures the current paint of all named elements and the root as "before" snapshots.
  3. It calls the callback and waits for its returned promise to resolve.
  4. It captures the post-callback paint as "after" snapshots.
  5. It resumes rendering and begins animating between the snapshots.

Because the browser controls steps 2 and 4, the snapshots are guaranteed to be consistent with each other. There is no race condition between "take screenshot" and "swap DOM": the rendering pipeline treats both as one atomic operation.

The snapshots are real composited pixel captures rendered to a texture, not references to the live DOM. During the animation, ::view-transition-old(name) is a frozen image of what the element looked like before, and ::view-transition-new(name) is a frozen image of what it looks like after. Neither one updates if the underlying DOM changes again mid-animation, because each is a static image, not an element.

Level 1 vs Level 2 ​

The View Transition API is specified in two levels:

Level 1 covers same-document transitions: transitions triggered by JavaScript within a single page. The entry point is document.startViewTransition(), a JavaScript API. Level 1 is what this article covers, and it requires the developer to explicitly call startViewTransition and put the DOM mutation in the callback.

Level 2 covers cross-document transitions: transitions between different page URLs, in multi-page applications (MPAs) where the browser navigates to a new document. These require no JavaScript: the browser detects the @view-transition { navigation: auto; } CSS rule and automatically wraps navigations in the snapshot machinery. Level 2 is covered in FEE-11104.

Why the default is a cross-fade ​

The UA stylesheet sets the default transition duration to 250ms (animation-duration: 0.25s) as an opacity cross-fade of the entire page root; this comes from the CSS View Transitions Level 1 user-agent style sheet, not a browser-specific convention. The choice is intentional: a cross-fade works between any two states, requires no knowledge of the layout, and avoids directional assumptions. More specific transitions (slide, morph, reveal) require the developer to express intent through named elements and custom keyframes.

Framework integration and newer primitives ​

Two additions build on the raw API described above. startViewTransition({update, types}) accepts a types array; paired with the :active-view-transition-type() CSS pseudo-class, it lets one stylesheet branch the animation by transition type, for example a forwards push versus a backwards pop, without extra JavaScript branching logic. React ships an experimental <ViewTransition> component in the React Canary channel that wraps startViewTransition and coordinates it with React's render cycle, so a shared name prop connects an unmounting and a mounting <ViewTransition> across different component trees. Neither addition replaces the mechanism described in this article: both compile down to the same document.startViewTransition() call and the same pseudo-element tree.

Browser Support ​

BrowserSame-Document View TransitionsNotes
Chrome111First implementation
Edge111Chromium-based
Firefox144Shipped in Firefox 144
Safari18iOS Safari 18 also supported

Feature detection:

js
if (document.startViewTransition) {
  // View Transitions Level 1 is supported
}

Or in CSS (useful for cross-document Level 2, but also documents same-document support via feature query):

css
@supports (view-transition-name: none) {
  /* View Transitions are supported */
}

Progressive enhancement pattern: always provide an instant-swap fallback for unsupported browsers, and disable animations for users who prefer reduced motion. Both checks are independent and both should be present.

Same-document view transitions became Baseline Newly Available in 2025, meaning they are supported across all three major browser engines. Cross-document (Level 2) transitions have narrower support: as of mid-2026, Chrome and Edge 126+ and Safari 18.2+ ship them, while Firefox has not shipped support. See FEE-11104 for the full comparison.

  • FEE-11104 View Transitions — Level 2 — Cross-document (MPA) transitions using @view-transition { navigation: auto; }. No JavaScript required; the browser wraps navigations automatically. Level 2 is the natural next step after mastering Level 1.
  • FEE-11101 @starting-style — Entry Animations Without JavaScript — Related entry animation topic. @starting-style provides the "before" snapshot for elements entering the DOM, which is complementary to view transitions: @starting-style handles individual element entry, while View Transitions handle full-page or multi-element state changes.

References ​