<ViewTransition> (stable since React 19.3) marks part of the tree that React should animate with the browser's View Transitions API. React decides when and which elements; the browser captures and animates them.
Which updates animate. Only non-urgent ones: state updates inside startTransition, updates from useDeferredValue, and Suspense boundaries revealing their content. A plain setState from a click commits immediately with no animation, because urgent updates should show at once. When a qualifying commit touches a boundary, React calls document.startViewTransition() and applies the DOM mutations inside its update callback.
How a boundary activates, per Transition:
- enter: the boundary is inserted. It must come before any DOM node in the inserted subtree; one nested inside a new
<div>doesn't count. - exit: the boundary is removed, with the same rule.
- update: React mutates DOM inside it, or it moves or resizes because of a sibling. A nested boundary takes the update instead of its parent.
- share: a boundary with a
nameis removed and another with the samenameinserted in the same Transition; the browser morphs one into the other.
Names. React puts view-transition-name inline on the boundary's nearest DOM nodes only while the transition is being set up, generating unique names, then removes them. Give name only for shared elements, and keep it unique among mounted boundaries.
Styling. Each trigger prop (enter, exit, update, share, default) takes "auto", "none" or a class name, which React sets as view-transition-class, so CSS can target ::view-transition-new(.slide-in). A prop can also be an object keyed by Transition type: call addTransitionType('navigation-back') inside startTransition to record the cause, and React picks the matching class and passes the types to the browser. Event props (onEnter, onExit, onUpdate, onShare) hand you the pseudo-elements for Web Animations instead.
Without browser support, React commits normally, without animating.