Skip to content
Tutorials Center
My learning

Topics

Lesson 103 of 139 ยท Transforms and Animation

View Transitions

Animate between page states with the View Transition API. Learn startViewTransition(), view-transition-name, its pseudo-elements and cross-page support.

Some changes are hard to animate with transitions or keyframes. A list is re-sorted. A thumbnail opens into a full detail view. A whole section of the page is replaced with new content. The old elements disappear and new ones appear, so there's no single element whose properties change smoothly.

The View Transition API solves this with a clever trick. The browser takes a snapshot of the page before the change, lets you update the DOM however you like, takes a snapshot after, and then animates between the two pictures. By default you get a smooth crossfade. With one CSS property, matching elements glide from their old position and size to their new ones.

This lesson covers same-document view transitions, which you start from JavaScript, how to customize them with CSS, and the newer cross-document transitions between separate pages.

Browser support

Be aware of where this works before you build on it:

  • Same-document transitions (document.startViewTransition()): Chrome and Edge 111 (2023), Safari 18 (2024) and Firefox 144 (late 2025).
  • Cross-document transitions (between two pages of a site): Chrome and Edge 126 (2024) and Safari 18.2 (late 2024). Firefox doesn't support them at the time of writing.

The good news is that view transitions are a pure enhancement. If the browser doesn't support them, you perform the update without animation, and the page works exactly the same. Every example below does this check.

Starting a transition

You start a same-document transition by passing a function that updates the DOM to document.startViewTransition():

JavaScript
function updateView(update) {
  // No support? Just make the change.
  if (!document.startViewTransition) {
    update();
    return;
  }
  document.startViewTransition(update);
}

updateView(() => {
  panel.textContent = 'New content';
});

Here is what happens step by step:

  1. The browser captures a screenshot of the current page.
  2. It calls your update function. The DOM changes, but rendering is paused so the user doesn't see a jump.
  3. It captures the new state of the page.
  4. It shows both snapshots in a layer of pseudo-elements on top of the page and animates from old to new. When the animation finishes, the layer is removed and the real, updated page is revealed.

startViewTransition() returns a ViewTransition object with three promises you can wait for: updateCallbackDone (your function has finished), ready (the animation is about to start) and finished (everything is done). It also has a skipTransition() method. Your update function can be async, which is handy if it needs to wait for data.

A crossfade between two states

The whole page crossfades: the old snapshot fades out while the new one fades in. That's the default, and it requires no CSS at all. The CSS in this example only slows it down.

The pseudo-element tree

While a transition runs, the browser builds this tree of pseudo-elements on top of the page:

TEXT
::view-transition
โ””โ”€ ::view-transition-group(root)
   โ””โ”€ ::view-transition-image-pair(root)
      โ”œโ”€ ::view-transition-old(root)   โ† screenshot of the old state
      โ””โ”€ ::view-transition-new(root)   โ† live picture of the new state

root is the name the browser gives to the whole page. Each pseudo-element has default animations: the old image fades out, the new image fades in, and the group animates size and position (which, for the root, usually don't change). You customize the transition by styling these pseudo-elements with ordinary CSS animation properties:

CSS
@keyframes slide-out { to { translate: -40px 0; opacity: 0; } }
@keyframes slide-in  { from { translate: 40px 0; opacity: 0; } }

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

The wildcard * targets every group: ::view-transition-group(*) { animation-duration: 500ms; }.

Naming elements with view-transition-name

The real magic starts when you give an element a view-transition-name:

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

The browser now captures that element separately from the root. If an element with the same name exists in the old state and in the new state, the browser treats them as the same thing. It gets its own ::view-transition-group(hero), which moves and resizes from the old box to the new box, while the two snapshots crossfade inside it. The two elements don't even need to be the same DOM node. A small thumbnail can grow into a big header image on the detail view.

There is one strict rule: a name must be unique among rendered elements at capture time. If two visible elements share a name, the transition is skipped and an error appears in the console. For lists, give each item its own name, often by setting it inline from a template or script.

A thumbnail that grows into a detail view

The script moves the name carefully so it is never on two visible elements at once. Before the transition, only the clicked tile is called card. Inside the update, the name moves to the panel, which is the only card in the new state. On the way back, the reverse happens.

Animating list changes

Give each item in a list a unique name and you get smooth reordering, insertion and removal almost for free. Items that exist in both states glide to their new positions. Items that only exist in the new state fade in, and items that only existed in the old state fade out.

Shuffling and removing list items

To style one kind of element without listing every name, newer browsers support view-transition-class. Give all the list items view-transition-class: task and target them with ::view-transition-group(*.task). Support for this is more recent, so treat it as an enhancement.

The page is not interactive during a transition. The pseudo-element layer sits on top of everything, so clicks during those few hundred milliseconds go nowhere. Keep transitions short, around 200โ€“500ms, so nobody notices.

Cross-document view transitions

The same effect can work across real page loads, in a multi-page site with no JavaScript. Both the old and new page opt in with an at-rule:

CSS
@view-transition {
  navigation: auto;
}

Now, when the user follows a link to another page on the same origin, the browser captures the old page, loads the new one, and crossfades between them. Elements with matching view-transition-name values on the two pages morph into each other, just like in the examples above. For finer control, JavaScript can listen to the pageswap event on the old page and the pagereveal event on the new one.

Cross-document transitions only run for same-origin navigations, and only in Chromium browsers and Safari 18.2 or later. They can't be demonstrated in the sandboxed editors on this site, which is why this section uses a read-only example. Other browsers just navigate normally.

Accessibility and reduced motion

A crossfade is mild, but morphing and sliding elements is real motion. Every example above includes this rule, which you can copy into your own projects:

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

Also remember to manage focus. When a transition replaces content, as in the detail view above, move keyboard focus somewhere sensible in the new state so keyboard and screen reader users aren't left on an element that has disappeared.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does document.startViewTransition(update) do first?

    The browser snapshots the old state, then calls your update, then captures the new state and animates between the two.
  2. 2. What is the default animation of a view transition with no extra CSS?

    By default, the old snapshot fades out while the new one fades in.
  3. 3. What happens if two visible elements share the same view-transition-name when the snapshot is taken?

    Names must be unique among rendered elements. A duplicate makes the browser skip the transition and log an error.
  4. 4. How should code handle browsers without the View Transition API?

    View transitions are an enhancement. Without support, perform the DOM update directly and the page works the same, just without animation.
  5. 5. Which CSS opts both pages into cross-document view transitions?

    The @view-transition at-rule with navigation set to auto must be present on both the old and the new page, which must be same-origin.

Summary

  • View transitions animate between two states by snapshotting the page before and after a DOM update.
  • Start one with document.startViewTransition(update); feature-detect it and fall back to a plain update.
  • The default effect is a crossfade; customize it by styling ::view-transition-old(), ::view-transition-new() and ::view-transition-group().
  • view-transition-name makes matching elements morph between positions and sizes; names must be unique.
  • @view-transition { navigation: auto; } enables transitions between same-origin pages in Chromium and Safari.
  • Disable the pseudo-element animations under prefers-reduced-motion: reduce, and manage focus.

Next: Motion, Performance and prefers-reduced-motion โ€” keep animations smooth and comfortable for everyone.