View Transitions API: Smooth animations between DOM states

The View Transitions API makes your web app feel native without animation libraries.

It creates smooth transitions between different DOM states. When a user clicks a thumbnail to see the full image, or filters a list, or navigates between pages—the browser handles the animation automatically.

Before this API, you’d reach for libraries like Framer Motion or React Spring to animate DOM changes. Those libraries work, but they add bundle size, require learning new APIs, and can be complex to integrate. The View Transitions API is built into the browser and works with any framework—or no framework at all.

The browser does the heavy lifting. You tell it when the DOM changes. It captures what the page looked like before, what it looks like after, and animates between those two states. No manual keyframe management, no calculating element positions, no performance optimization needed.

How it works

Call document.startViewTransition() and pass it a function that updates the DOM. The browser captures a snapshot of the old state, executes your function, captures the new state, and animates between them.

The API works in three phases. First, the browser takes a screenshot of the current page. Second, it calls your callback function to update the DOM. Third, it takes another screenshot and animates from the old screenshot to the new one. This happens in a single frame, so users never see the instant DOM change—only the smooth animation.

1
function updateView() {
2
  // Check browser support
3
  if (!document.startViewTransition) {
4
    updateTheDOMSomehow();
5
    return;
6
  }
7

8
  // Wrap DOM changes in a transition
9
  document.startViewTransition(() => updateTheDOMSomehow());
10
}

The default animation is a cross-fade. No CSS required. The browser figures out what changed and animates it.

Try it: Click the button below to see the basic transition in action.

The transition returns a promise that resolves when the animation completes. Use this to chain actions or trigger cleanup:

1
const transition = document.startViewTransition(() => {
2
  document.querySelector('#content').textContent = 'New content';
3
});
4

5
// Wait for the animation to finish
6
await transition.ready;
7
console.log('Transition started');
8

9
await transition.finished;
10
console.log('Transition completed');

If your callback throws an error or returns a rejected promise, the transition aborts. The DOM still updates, but without animation. This fail-safe behavior means transitions enhance the experience without breaking core functionality.

For multi-page apps, add this CSS to enable transitions between different pages:

1
@view-transition {
2
  navigation: auto;
3
}

Now when users click links, the browser animates between pages instead of doing a hard navigation. This works in Chrome 126+, Edge 126+, and Safari 18.2+.

You can customize which navigations trigger transitions. Use JavaScript to control this per-navigation:

1
navigation.addEventListener('navigate', (event) => {
2
  if (shouldNotTransition(event)) {
3
    return; // Skip transition
4
  }
5

6
  event.intercept({
7
    handler: async () => {
8
      document.startViewTransition(() => {
9
        // Load new content
10
      });
11
    }
12
  });
13
});

Custom animations

Use CSS pseudo-elements to control how transitions look. The API creates several pseudo-elements during each transition:

• ::view-transition - the root overlay containing all transitions
• ::view-transition-group() - groups related elements
• ::view-transition-image-pair() - contains both old and new snapshots
• ::view-transition-old() - snapshot of the previous state
• ::view-transition-new() - live view of the new state

These pseudo-elements exist only during the transition. The browser creates them, animates them, then removes them. You can style them like any CSS element—transform, opacity, filter, whatever you need.

1
::view-transition-old(root) {
2
  animation: slide-out-left 0.3s ease-out;
3
}
4

5
::view-transition-new(root) {
6
  animation: slide-in-right 0.3s ease-out;
7
}
8

9
@keyframes slide-out-left {
10
  to { transform: translateX(-100%); }
11
}
12

13
@keyframes slide-in-right {
14
  from { transform: translateX(100%); }
15
}

This creates a slide transition instead of the default fade.

Try it: Navigate through the steps to see the custom slide animation.

For specific elements, use view-transition-name in CSS to create named transitions:

1
.thumbnail {
2
  view-transition-name: product-image;
3
}
4

5
.fullscreen {
6
  view-transition-name: product-image;
7
}

When an element with view-transition-name: product-image disappears and another appears with the same name, the browser morphs between them. The thumbnail smoothly expands into the fullscreen view.

The browser tracks the element’s position, size, and other properties, then animates from the old state to the new state. This works even when the elements are completely different—one could be a 200px thumbnail and the other a full-screen modal. The browser figures out the transformation needed.

Try it: Click any image to see it smoothly morph into fullscreen.

Named transitions work because the browser matches elements by their view-transition-name. If an element with product-image exists before and after the transition, the browser knows they’re related and creates a morph animation. If only one exists, it fades in or out. If multiple elements have the same name, the last one wins.

You can animate multiple elements independently by giving them unique names:

1
.card-1 { view-transition-name: card-1; }
2
.card-2 { view-transition-name: card-2; }
3
.card-3 { view-transition-name: card-3; }

Each named element gets its own pseudo-element tree. You can style them separately:

1
::view-transition-old(card-1) {
2
  animation: fade-out 0.3s ease-out;
3
}
4

5
::view-transition-new(card-1) {
6
  animation: fade-in 0.3s ease-in;
7
}

This also works for animating list reordering. Give each item a unique view-transition-name and the browser animates them to their new positions:

1
.list-item-1 { view-transition-name: item-1; }
2
.list-item-2 { view-transition-name: item-2; }
3
.list-item-3 { view-transition-name: item-3; }

Try it: Click shuffle to see items animate to their new positions.

The browser calculates the shortest path between old and new positions for each named element. Items that move animate smoothly to their new locations. Items that disappear fade out. Items that appear fade in. All coordinated automatically.

Dynamic transition names work with JavaScript. Generate names based on data:

1
items.forEach((item, index) => {
2
  const element = document.querySelector(`#item-${item.id}`);
3
  element.style.viewTransitionName = `item-${item.id}`;
4
});
5

6
document.startViewTransition(() => {
7
  // Reorder items
8
  items.sort(() => Math.random() - 0.5);
9
  renderItems(items);
10
});

Each item keeps its identity across the transition. The browser tracks where each one moves and animates it there.

Performance considerations

View Transitions are fast. The browser captures bitmap snapshots of elements, which is cheaper than animating actual DOM nodes. Snapshots render on the GPU, so animations run at 60fps even on slower devices.

The snapshots are temporary. They exist only during the transition—usually 200-400ms. After the animation completes, they’re discarded. This means no memory leaks or lingering overhead.

Transitions don’t block the main thread. The browser captures snapshots, starts the animation, then continues executing JavaScript. Your app stays responsive during transitions.

If a transition takes too long, the browser caps it. Transitions longer than 1 second are suspicious—usually a sign of forgotten cleanup. The browser enforces reasonable limits to prevent stuck states.

Using with frameworks

React has experimental support via unstable_ViewTransition:

1
import { unstable_ViewTransition as ViewTransition, useState, startTransition } from 'react';
2

3
function Item() {
4
  return (
5
    <ViewTransition>
6
      <div>Content here</div>
7
    </ViewTransition>
8
  );
9
}
10

11
export default function Component() {
12
  const [showItem, setShowItem] = useState(false);
13

14
  return (
15
    <>
16
      <button onClick={() => {
17
        startTransition(() => {
18
          setShowItem(prev => !prev);
19
        });
20
      }}>
21
        Toggle
22
      </button>
23
      {showItem ? <Item /> : null}
24
    </>
25
  );
26
}

The experimental React API requires installing React canary builds:

1
npm install react@experimental react-dom@experimental

Don’t use this in production. The API is unstable and will change.

Vue, Svelte, and other frameworks work with the standard API. No special wrappers needed—just call document.startViewTransition() when state changes. Most frameworks trigger DOM updates synchronously within the callback, which is exactly what the API expects.

For SPAs using client-side routing, wrap route changes in transitions:

1
// With React Router
2
navigate('/new-page');
3
// becomes
4
document.startViewTransition(() => {
5
  navigate('/new-page');
6
});
7

8
// With Vue Router
9
router.push('/new-page');
10
// becomes
11
document.startViewTransition(() => {
12
  router.push('/new-page');
13
});

Astro has built-in support through <ViewTransitions />. Add the component to your layout and page transitions happen automatically. You can customize transition names per-page using the transition:name directive.

Common patterns

Conditional transitions based on user preference:

1
function updateWithTransition(updateFn) {
2
  if (prefersReducedMotion()) {
3
    updateFn();
4
    return;
5
  }
6

7
  document.startViewTransition(updateFn);
8
}

Skip transitions for fast repeated actions:

1
let lastTransition = 0;
2
function updateIfReady(updateFn) {
3
  const now = Date.now();
4
  if (now - lastTransition < 300) {
5
    updateFn(); // Too soon, skip transition
6
    return;
7
  }
8

9
  lastTransition = now;
10
  document.startViewTransition(updateFn);
11
}

Different transitions for different actions:

1
document.documentElement.dataset.transition = 'slide';
2
document.startViewTransition(() => {
3
  navigate('/next');
4
});
5

6
// In CSS
7
:root[data-transition='slide'] ::view-transition-old(root) {
8
  animation: slide-out 0.3s;
9
}

Browser support

Same-document transitions work in Chrome 111+, Edge 111+, Firefox 144+, and Safari 18+.

Cross-document transitions (the multi-page app feature) work in Chrome 126+, Edge 126+, and Safari 18.2+. Firefox doesn’t support it yet.

The API degrades gracefully. If the browser doesn’t support it, your DOM updates still work—they just don’t animate. This makes it safe to use today. Check for support with 'startViewTransition' in document before calling.

The API is stable. Chrome shipped it in 2023. Other browsers followed. It’s not experimental anymore—it’s production-ready. Use it for product galleries, navigation between pages, filtering lists, expanding cards, or any UI change where you want smooth motion instead of instant replacement.

The View Transitions API handles the animation complexity so you don’t have to. No more manual position tracking, no more complex state management, no more animation libraries for basic transitions. The browser does it all.