Limitations and troubleshooting
Available from 4.8.0
The view does not move
Check these points:
- Both views have the same
sharedTransitionTag, and each tag shows only once on a screen. - Each screen is in a
SharedTransitionBoundary, andisActivechanges from the old screen to the new screen when you navigate. - No boundary that is always active is around the boundaries of your screens, for example a boundary around a nested navigator.
- Both views are mounted when the active boundary changes. A view that mounts later, for example after its data loads, does not move. On Android, a view with a
nativeIDprop must mount before the update that changesisActive. - Both views are animated components of the same native type, for example
Animated.ViewandAnimated.View. With different types, a debug build stops on an assertion. - The tag is on a component with its own native view. A
Textinside anotherTexthas no native view, so it cannot be a shared view. - The view is not in a native header. React Navigation renders
headerTitle,headerLeftandheaderRightoutside of the screen, so they are outside of its boundary. Put the view in the content of the screen, or hide the native header and render your own header in the screen. - Both views are in the same window. See Modals and windows.
- The
USE_LEGACY_LAYOUT_ANIMATIONS_PROXYfeature flag is off. The legacy layout animations proxy does not support Shared Element Transitions.
When Reanimated cannot run a transition, the two views show in their own places, and the callback of .withCallback() gets false.
Modals and windows
A shared view moves only between two views in the same window.
- On Android, a React Native
Modalhas its own window. A view can move between two views in the sameModal. It cannot move between the screen and aModal, between twoModals, or to or from a sheet that a library shows in its own window. - On iOS, both views must be in the window of the React Native root view or in a modal presented over it. A view cannot move to or from another
UIWindow. - On iOS, the view lands only when the screen of the target is in the window. If the screen is not there 500 ms after its boundary becomes active, the transition stops.
Updates during the transition
- React updates to the props or the layout of the moving view apply when the transition ends, which can look like a jump. This includes
useAnimatedStyleupdates that go through React. The children of the moving view update during the move. - A style change of the target view also shows only when the transition ends.
- A view that moves with a built-in timing or spring animation follows its target when a transform moves the parents of the target or when a scroll view scrolls the target. A custom animation or a timed progress animation does not: it moves to the place that the target had when the move started.
- If the layout of the target changes during the transition, the view starts a new move from its current frame. The new move can take the full duration again.
- With the
USE_ANIMATION_BACKENDfeature flag, the moving view does not follow the transforms that the animation backend applies to the parents of the target. Disable the flag if these parents move during a transition. - A text input that the target screen focuses when it opens shows the keyboard during the transition. If the keyboard moves the target view, for example in a
KeyboardAvoidingView, the moving view changes its course. Focus the input when the transition ends: use the.withCallback()callback of the outermost shared view, whenfinishedistrue. ThetransitionEndevent of the screen can come while the view still moves.
Known issues
- On iOS, a screen that a native stack shows for the first time gets its header size a moment later. A view that moves to such a screen, for example to the first screen of a nested stack, can first move too high and then move down.
- On iOS, if the header of a covered screen changes, for example after a theme change, a view that goes back to this screen can stop at the old place and then jump.
- The first time that the user opens a tab, a view that moves to the new tab screen can stay at its old place for a moment and then jump to its target. On iOS, this happens with the default
detachInactiveScreensof bottom tabs, anddetachInactiveScreens={false}prevents it. On Android, it happens withfreezeOnBlur. - Reanimated does not see screen animations that run with the native driver of React Native
Animated, for example the screen animations of@react-navigation/stackor thefadeanimation of bottom tabs. A view that moves to such a screen goes to the place where the screen starts its animation, and then jumps when the animation ends. Use@react-navigation/native-stack, or bottom tabs without an animation. - On Android, a view that moves into a sheet that a native library positions, for example the sheet of
@swmansion/react-native-bottom-sheet, moves to a place without the offset of the sheet and then jumps to its target. A sheet that React positions, for example@gorhom/bottom-sheet, does not have this issue. On iOS, a built-in transition follows the sheet. - A view between a nested shared view and its shared parent keeps its source size and place during the move, so its
overflow: hiddenand its background can look wrong. Put the clipping and the background on the shared parent, or give that view its ownsharedTransitionTag. - During development, a Fast Refresh can start a transition between the old and the new version of a view on the same screen. This does not happen in release builds.
Videos and media
The moving view keeps its own content, for example an image or a video player, until the transition ends.
For images:
- The moving image keeps its
resizeMode. TheresizeModeof the target, for examplecontainaftercover, shows when the transition ends. - The target image shows when the transition ends, also when it is still loading. To prevent an empty image, use the same image source on both screens. For example, share the thumbnail, and show the full image above it on the details screen when it loads.
For videos with expo-video:
- On iOS, give the same video player to the video views on both screens. Then the playback continues from the same position.
- On Android, expo-video cannot show one player in two mounted views. Use a separate player on each screen. The two players can be at different positions, so the video can jump when the target shows. See the expo-video guide.
- On Android, set
surfaceType="textureView"on aVideoViewthat moves over other content. ATextureViewmoves and overlaps like other views, but it cannot show DRM content. useVideoPlayerreleases its player when its component unmounts, also when the shared view still moves, for example afternavigation.goBack(). Create the player in a component that stays mounted, for example above the navigator, or create it withcreateVideoPlayerand callrelease()when no view needs it.