React Reference ยท Components and Special Elements
The ViewTransition component
Reference for React ViewTransition: animate DOM changes with the browser View Transitions API, name shared elements, and check availability.
ViewTransition connects React updates to the browser's View Transitions API. You wrap the elements that should animate. When an update runs inside a transition and changes the wrapped content, React asks the browser to take a snapshot of the old state, applies the DOM change, and lets the browser animate from old to new. By default you get a short cross-fade; CSS lets you change that.
It animates four kinds of change: an element entering the page, exiting it, updating (its size or position changes), and sharing a name between an element that disappears and one that appears elsewhere, so it appears to move.
ViewTransition is newer than most of React. Depending on the release channel and version it is exported as ViewTransition, or only from Canary and experimental builds (sometimes as unstable_ViewTransition). The editor on this site loads React 19.3.1, where ViewTransition is exported, but read the release notes of the version you ship before building on it.
import { ViewTransition, startTransition } from 'react'; startTransition(() => setPage('details')); <ViewTransition> <Page /> </ViewTransition>
Try it
In the first example the console prints whether the component exists and whether the browser supports the underlying API. Without browser support, or without the component, the page simply updates with no animation; nothing breaks. The second example asks for custom enter and exit animations by class name; it only animates in browsers that support view transitions.
Syntax
<ViewTransition name={string} default={'auto' | 'none' | className} enter={'auto' | 'none' | className} exit={'auto' | 'none' | className} update={'auto' | 'none' | className} share={'auto' | 'none' | className} > {children} </ViewTransition>
| Name | Description |
|---|---|
name |
Optional. A unique string that names the element for shared-element animations. If you omit it, React generates one. Two ViewTransitions with the same name must not be on screen at once. |
default |
The animation used when a more specific prop is not given. "auto" is the browser cross-fade, "none" disables animation, anything else is a CSS class applied to the transition pseudo-elements. |
enter, exit |
The animation when the content appears for the first time or is removed. |
update |
The animation when the content stays but its size, position or content changes. |
share |
The animation when a named element is replaced by another with the same name. |
children |
The content to animate. It should contain at least one DOM element. |
Some releases also accept callback props (such as onEnter and onExit) that receive the underlying animation handle. Treat these as experimental.
Usage notes
- Only transitions animate. Updates that run inside
startTransition,useTransition,useDeferredValueor a Suspense reveal can animate. An ordinary urgentsetStatedoes not, and neither doesflushSync. - Suspense. A boundary that goes from fallback to content can cross-fade if a
ViewTransitionwraps it. - Use CSS to style. The pseudo-elements
::view-transition-old(name)and::view-transition-new(name)and the classes you pass in props are the styling hooks. Durations and easing belong in CSS. - Names must be unique. Duplicates on the same page make the browser skip the transition. Derive names from stable IDs, for example
"photo-" + id. - It animates the visible change only. Elements outside the viewport are not animated, and elements inside the wrapper are captured as one image.
- Reduce motion. Wrap animation CSS in
@media (prefers-reduced-motion: no-preference)so people who asked for less motion are not forced to see it. - Browser support varies. Always treat the animation as an enhancement; the final state must be correct without it. Check the browser API with
document.startViewTransition. - Stacking and cost. The browser captures bitmaps of the page, so very large or highly dynamic wrappers can be heavy. Wrap only what must move.
Related
- useTransition, startTransition, Activity, Suspense
- Lessons: Animation, Transitions