Shared Element Transitions
Shared Element Transitions move a view from one screen to another. When you navigate, a view on the old screen moves to the position of the matching view on the new screen. Its size and style change during the transition.
Setup
This chapter describes Shared Element Transitions in Reanimated 4.8 and newer, where they are on by default. They need the matching version of react-native-worklets and a React Native version that Reanimated supports. See the compatibility table. Reanimated 4.2 to 4.7 have an experimental version behind the ENABLE_SHARED_ELEMENT_TRANSITIONS feature flag.
- Expo: an Expo SDK selects the versions that
npx expo installinstalls, and it can select a Reanimated version older than 4.8. Use an Expo SDK with a React Native version that Reanimated 4.8 supports. Install Reanimated 4.8 or newer together with the matchingreact-native-worklets, and then build your development build again. Expo Go has only the native code of the versions that its SDK selects. - Android: use
react-native-screens4.28 or newer. In older versions, an app can crash inMountingCoordinator::pullTransactionafter a race at startup. See react-native-screens#4413. After you upgrade it, build the app again.
Your first shared element transition
import { Pressable } from 'react-native';
import { useIsFocused } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import Animated, { SharedTransitionBoundary } from 'react-native-reanimated';
const Stack = createNativeStackNavigator();
function ListScreen({ navigation }) {
return (
<Pressable onPress={() => navigation.navigate('Details')}>
<Animated.View
sharedTransitionTag="photo"
style={{ width: 100, height: 100, backgroundColor: '#b58df1' }}
/>
</Pressable>
);
}
function DetailsScreen() {
return (
<Animated.View
sharedTransitionTag="photo"
style={{ width: '100%', height: 300, backgroundColor: '#b58df1' }}
/>
);
}
function ScreenBoundary({ children }: { children: React.ReactNode }) {
const isFocused = useIsFocused();
return (
<SharedTransitionBoundary isActive={isFocused}>
{children}
</SharedTransitionBoundary>
);
}
function App() {
return (
<Stack.Navigator
screenLayout={({ children }) => <ScreenBoundary>{children}</ScreenBoundary>}>
<Stack.Screen name="List" component={ListScreen} />
<Stack.Screen name="Details" component={DetailsScreen} />
</Stack.Navigator>
);
}
To make a shared element transition:
- Give the same
sharedTransitionTagto an animated component on each screen. - Wrap each screen in a
SharedTransitionBoundary. SetisActivetotrueon the screen that the user sees. In the example, thescreenLayoutprop of the navigator wraps all of its screens. For other ways to wrap screens, see Usage with navigation.
When the active boundary changes, Reanimated finds the views with the same tag in the old and the new boundary and runs the transition between them.
How it works
During the transition, Reanimated moves the view from the old screen above the screen content and hides the view on the new screen. Then it animates the moving view from its old frame and style to the frame and style of the new view. When the animation ends, the view on the new screen shows in its place.
By default, the transition is a 500 ms withTiming animation of every property that is different on the two views:
- position and size,
opacityandbackgroundColor,borderRadius,borderWidthandborderColor, also per side and per corner,transformandtransformOrigin,boxShadowand theshadow*properties,- on Android,
elevation.
The view moves together with its own children, and the children of the target view show at once when the transition ends. To fade between different children, use fadeContent().
Example
const isFocused = useIsFocused();
return (
<SharedTransitionBoundary isActive={isFocused}>
{children}
</SharedTransitionBoundary>
);
}
export default function GalleryExample() {
return (
<Stack.Navigator
screenLayout={({ children }) => (
<ScreenBoundary>{children}</ScreenBoundary>
)}
screenOptions={{
headerShown: false,
}}>
<Stack.Screen name="Home" component={HomeScreen} />
<Stack.Screen name="Details" component={DetailsScreen} />
</Stack.Navigator>
);
}
What's next
- Shared transition props - how views find their match and which transition they use.
- Screens and boundaries - how to set up screens in stacks, tabs, nested navigators and modals.
SharedTransition- how to change the duration, the easing, or to use a spring.- Children of shared views, Custom animations and Progress-based transitions - for more control.
- Limitations and troubleshooting - what to know before you release your app.
Platform compatibility
| Android | iOS | Web |
|---|---|---|
| ✅ | ✅ | ❌ |
On web, SharedTransitionBoundary renders only its children, and shared views show in their places without a transition.