This page details React's integration with the View Transitions API, focusing on how the reconciler (ReactFiberCommitViewTransitions.js) manages these transitions, the scheduling of gesture-driven transitions, the ViewTransition component, and the implementation of swipe-based transitions in the provided fixture.
React integrates with the browser's View Transitions API to enable smooth visual transitions between different DOM states. This integration is primarily handled within the reconciler, specifically in ReactFiberCommitViewTransitions.js and ReactFiberApplyGesture.js. The core idea is to identify elements that should participate in a view transition, capture their states before and after a DOM update, and delegate the animation to the browser's native mechanism.
The ViewTransition component is the primary interface for developers. It tracks internal state via ViewTransitionState defined as:
This is implemented in packages/react-reconciler/src/ReactFiberViewTransitionComponent.js19-24
Key ViewTransition props include:
name: A string identifier for the transition. If omitted or set to 'auto', React generates a unique autogenerated autoName based on the root's identifierPrefix and a global client id counter lines 28-47default: Specifies CSS classes for default transition styling. It supports either a string or an object keyed by transition types for more granular control lines 79-91onShare: A hook (viewTransition, types) => cleanup exposing the old and new pseudo-elements (viewTransition.old, viewTransition.new) which enables custom animation logic during the transition commit. For example, to rotate elements synchronously (fixture source()).onGestureShare: Similar to onShare, but specifically designed to accept a timeline (e.g., AnimationTimeline or custom timeline) and range progress to enable gesture-driven custom animations (fixture source()).The reconciler orchestration mainly occurs in ReactFiberCommitViewTransitions.js:
Detection: During the commit phase, React identifies new or updated Fibers of type ViewTransitionComponent. Upon detecting such fibers, it sets a global boolean flag shouldStartViewTransition to true indicating that a view transition should be started this commit. Named transitions are tracked in a map appearingViewTransitions keyed by their transition name (lines 60-90).
Before Mutation Phase:
trackDeletedPairViewTransitions in ReactFiberApplyGesture.js (lines 146-200).view-transition-name property to host instances using the applyViewTransitionToHostInstances function. When a boundary has multiple host instances, the reconciler generates unique suffixed names (e.g., name_1, name_2) (lines 113-134).measureInstance to determine viewport visibility for analytics or optimisation (lines 191-193).Post-Mutation Phase:
scheduleViewTransitionEvent or scheduleGestureTransitionEvent that triggers the browser's native document.startViewTransition and invokes custom transition hooks such as onShare and onGestureShare (lines 38-41).The following table summarizes key functions and their roles:
| Function | File Path | Description |
|---|---|---|
getViewTransitionName | ReactFiberViewTransitionComponent.js | Resolves CSS transition name, generating auto-names if unspecified. |
applyViewTransitionName | Host Config (e.g. DOM) | Manipulates view-transition-name CSS property on host Instances. |
trackEnterViewTransitions | ReactFiberCommitViewTransitions.js | Detects ViewTransition components during commit and marks transition start. |
measureInstance | Host Config (e.g. DOM) | Captures bounding box or layout information for host instances. |
Diagram: View Transition Reconciler Flow
Sources: packages/react-reconciler/src/ReactFiberCommitViewTransitions.js60-90 packages/react-reconciler/src/ReactFiberApplyGesture.js146-200 packages/react-reconciler/src/ReactFiberCommitViewTransitions.js113-134 packages/react-reconciler/src/ReactFiberCommitViewTransitions.js191-193 packages/react-reconciler/src/ReactFiberViewTransitionComponent.js19-24
React additionally supports gesture-driven view transitions, allowing UI updates to synchronize responsively with user gestures like touch swipe or scroll.
This gesture scheduling logic is in ReactFiberGestureScheduler.js. Gestures are represented as ScheduledGesture objects with the following shape:
(Defined in packages/react-reconciler/src/ReactFiberGestureScheduler.js31-43)
Scheduling a Gesture: When a gesture-controlled transition begins (e.g., user initiates a swipe), scheduleGesture adds a ScheduledGesture instance to the Fiber root's pendingGestures linked list and ensures the root is scheduled to render. This sets up React's internal coordination of the gesture lines 45-82
Starting a Gesture: startScheduledGesture initializes the gesture's rangeStart and rangeEnd from the current offset of the gesture timeline. This ensures React knows the beginning progress point of the gesture transition lines 84-132
Cancelling or Settling a Gesture: cancelScheduledGesture handles the end of a gesture interaction by determining if the transition should "commit" (complete) or revert (cancel). It does so by comparing the progress offset to the halfway point (50%). If committing, it marks committing true and pings React to render at the gesture lane. Otherwise, it immediately calls stopViewTransition to revert (lines 134-200). The gesture event lifecycle is integrated with the scheduler and React's rendering system.
Diagram: Gesture Scheduling Flow
Sources: fixtures/view-transition/src/components/SwipeRecognizer.js88-123 packages/react-reconciler/src/ReactFiberGestureScheduler.js31-200 packages/react-reconciler/src/ReactFiberConfig.custom.js130-150
The fixtures/view-transition directory demos how to use these APIs for practical swipe-based navigation.
Page.js: Implements navigation state management with useOptimistic and signals transition types on swipe gestures. It uses ViewTransition components wrapping sections that animate on navigation. The component calls addTransitionType to register the navigation direction (navigation-forward or navigation-back), which dynamically affects CSS classes applied during transitions lines 94-101, 219-223SwipeRecognizer component detects and interprets swipe gestures. It interacts with unstable_startGestureTransition to coordinate gesture-controlled view transitions with React's reconciler lines 88-114 The gesture lifecycle is managed with callbacks that clean up when the gesture ends.The following diagram links conceptual components from the gestures and reconciler to key code entities holding those responsibilities:
Diagram: Code Entity Relationships
Sources: packages/react-reconciler/src/ReactFiberGestureScheduler.js31-43 packages/react-reconciler/src/ReactFiberCommitViewTransitions.js60-75 packages/react-reconciler/src/ReactFiberViewTransitionComponent.js19-24 packages/react-reconciler/src/ReactFiberApplyGesture.js22-23 fixtures/view-transition/src/components/Page.js94-101 fixtures/view-transition/src/components/SwipeRecognizer.js88-114
ViewTransition component exposes a convenient React interface with props for naming, default CSS, and hooks for animation sharing (onShare, onGestureShare).ScheduledGesture objects in the root and coordinating commit or cancellation based on gesture completion.Sources:
packages/react-reconciler/src/ReactFiberCommitViewTransitions.js
packages/react-reconciler/src/ReactFiberViewTransitionComponent.js
packages/react-reconciler/src/ReactFiberApplyGesture.js
packages/react-reconciler/src/ReactFiberGestureScheduler.js
fixtures/view-transition/src/components/Page.js
fixtures/view-transition/src/components/SwipeRecognizer.js
Refresh this wiki