View Transitions in React: morphing a card into a detail view

The one line most React examples leave out

If you have tried the View Transitions API in React and got nothing, no error and no animation, this is almost certainly why:

document.startViewTransition(() => {
  flushSync(() => setSelected(id));
});

startViewTransition screenshots the page, runs your callback, and screenshots it again the moment the callback returns. React batches state updates. So without flushSync the callback returns before the DOM has changed, the browser captures two identical snapshots, and it animates diligently between them: a perfect, invisible transition from a thing to itself.

There is no warning. Nothing throws. It simply does nothing, which is a much harder failure to debug than an exception would be.

flushSync is normally a smell, and React's own documentation says so, because it forces a synchronous re-render and abandons batching. This is the exception the documentation has in mind. You are not reaching for it to work around a render-timing bug; you are reaching for it because an external API needs the DOM committed at a specific instant.

Names, and why only one element can wear them

The morph itself is one property:

view-transition-name: --card-alu;

Put the same name on the grid card and on the detail panel it opens into, and the browser treats them as the same thing in two places. It captures the old box, captures the new one, and animates position, size and content between them.

The rule that catches people: a name must be unique among rendered elements. Two elements with the same view-transition-name on screen at once is an error, and the browser's response is to skip the entire transition. Not that group. All of it.

That is why this demo renders either the grid or the detail, never both. It also means the name cannot live in the stylesheet when the list is dynamic, since a stylesheet has no way to know how many items there are. It goes inline, derived from the item's id:

<button style={{ viewTransitionName: `lab-vt-${card.id}` }}>

The root snapshot will surprise you

startViewTransition does not capture the element you named. It captures the whole page, as ::view-transition-old(root) and ::view-transition-new(root), and cross-fades that, with your named elements animating as separate groups on top.

For a full-page navigation that is exactly right. For a demo embedded halfway down an article, it means clicking a card cross-fades the entire article, header and all. The first time I saw it I assumed I had broken something.

The fix is to opt the root out of animating:

::view-transition-old(root),
::view-transition-new(root) {
  animation: none;
}

Now only the named element moves. Worth knowing well beyond demos: any time you want a targeted morph rather than a page-level crossfade, this is the declaration that gets you there.

There is a trap in shipping it, and I walked into it here. Write those two selectors as a list, which is how every example on the web writes them, and a CSS minifier may merge them into :is(::view-transition-old(root), ...). :is() does not accept pseudo-elements: the browser strips them out, the selector collapses to a bare :is() matching nothing, and the rule is silently dead. The symptom is the whole page cross-fading again in production while it behaves in development, with no error anywhere. Keeping them as two separate rules survives minification intact.

Cross-document, and why this site cannot use it

The version of this API that gets the most attention is the cross-document one: add @view-transition { navigation: auto; } to two pages and navigating between them animates, with no JavaScript at all. It is genuinely remarkable, and it is the reason the API got so much attention when it shipped.

It also does not apply to this site, and it is worth being precise about why. Cross-document transitions run on real document navigations. Next's App Router intercepts internal links and swaps the page client-side, so no document navigation happens and the rule never fires. The same is true of every SPA router.

That is not a Next problem to be worked around. It is the trade: client-side routing buys you preserved state and no reload, and the cost is that the document-level transition primitive does not apply. What applies instead is the same-document API, which is what this demo uses, and React 19's <ViewTransition> component is a thinner way to reach it.

Treat it as an upgrade, not a feature

Both exits from this component are the same exit:

if (!document.startViewTransition || REDUCED?.matches) {
  setOpenId(next);
  return;
}

No support, or a reduced-motion preference, and the state changes instantly. That is the app you had before you added any of this. Nothing about the feature is load-bearing, which is the correct relationship to have with an API that a third of your visitors cannot run.

The reduced-motion branch is not politeness either. A morph is a large element travelling a long way across the viewport at speed, which is the exact motion profile the setting exists to remove.

One thing to do properly in a real app

Focus. When the view changes, the button that was focused stops existing, and focus falls back to <body>. A keyboard user is then at the top of the document with no idea the view changed.

The demo gets away with it because the detail's back button is the next thing in the tab order. A real implementation should move focus deliberately, to the heading of the incoming view, and announce the change. The animation is the easy half of a view change; this is the half that decides whether it is usable.