Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A view-transition-name is set but nothing animates in React

ErrorThe page changes instantly with no animation

Short answer

A view transition animates only if startViewTransition runs and the DOM changes inside its callback. In React, state updates are batched, so the DOM may not change in time; use flushSync inside the callback or the React ViewTransition component with a Transition. Two elements sharing one view-transition-name also cancels the whole transition.

  • Applies to React 19, browsers that support View Transitions
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Capture the transition object and log what happens to its ready promise. A rejection means the browser skipped the animation.

    const t = document.startViewTransition(() => updateView());
    t.ready.then(() => console.log('animating'), (e) => console.log('skipped', e));
  2. 2Match what you see, then jump to its fix

    1. 1ViewTransition.ready rejects; list or grid items all animate nothingTwo elements have the same view-transition-nameFix
    2. 2The transition starts but old and new views look identicalReact updates the DOM after the startViewTransition callback has finishedFix
    3. 3No animation although the component is wrapped in ViewTransitionA <ViewTransition> boundary is updated with a plain setStateFix
    4. 4document.startViewTransition is undefinedThe browser has no support for the APIFix

What does the error look like?

  • The page changes instantly with no animation
  • There are two <ViewTransition name=...> components with the same name mounted at the same time.
  • ViewTransition.ready rejects and the transition is skipped

Cause 1 of 4

Two elements have the same view-transition-name

1Check

The name must be unique for each rendered element taking part. A name set in a CSS class applied to every list item gives many elements one name.

grep -rn "view-transition-name" src/

2Fix

Give each element its own name, for example by including its id, or use match-element for same-document transitions.

<li style={{ viewTransitionName: `item-${item.id}` }}>{item.title}</li>

3Verify

Run the transition again. ready resolves and the animation plays.

# repeat the action with the console open

Confirmed by developer.mozilla.org

Did this fix it?

Cause 2 of 4

React updates the DOM after the startViewTransition callback has finished

1Check

The browser takes the old snapshot, runs your callback, and takes the new view when the callback's promise fulfills. React batches a setState and updates the DOM later, so the callback ends before anything changed.

document.startViewTransition(() => {
  setPage('next'); // DOM not updated yet
});

2Fix

Force the update to finish inside the callback with flushSync.

import { flushSync } from 'react-dom';

document.startViewTransition(() => {
  flushSync(() => setPage('next'));
});

3Verify

The old page animates into the new one.

# trigger the navigation in the browser

Confirmed by react.dev

Did this fix it?

Cause 3 of 4

A <ViewTransition> boundary is updated with a plain setState

1Check

A plain setState update does not activate ViewTransition. Only updates inside a Transition, Suspense or useDeferredValue do.

grep -rn "ViewTransition" src/

2Fix

Wrap the state update in startTransition and do not call startViewTransition yourself, because React calls it for you.

import { startTransition } from 'react';

startTransition(() => {
  setShowItem((prev) => !prev);
});

3Verify

The boundary animates when the state changes.

# toggle the state in the browser

Confirmed by react.dev

Did this fix it?

Cause 4 of 4

The browser has no support for the API

1Check

Test for the function before calling it.

console.log(typeof document.startViewTransition);

2Fix

Call your update directly when the function is missing, so the app still works without animation.

if (!document.startViewTransition) {
  updateView();
  return;
}
document.startViewTransition(() => updateView());

3Verify

In an unsupported browser the update still happens, with no error.

# open the page in a browser without the API

Confirmed by developer.mozilla.org

Did this fix it?

How do I stop it coming back?

  • Build names from stable ids, and keep a name mounted only once at a time.
  • Use flushSync only inside the startViewTransition callback; React advises it as a last resort.
  • Always keep the feature test, because the update must work without the API.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.