Skip to main content
Version: Unreleased

Shared Element Transitions

Available from 4.8.0

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.

Loading...

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 install installs, 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 matching react-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-screens 4.28 or newer. In older versions, an app can crash in MountingCoordinator::pullTransaction after 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:

  1. Give the same sharedTransitionTag to an animated component on each screen.
  2. Wrap each screen in a SharedTransitionBoundary. Set isActive to true on the screen that the user sees. In the example, the screenLayout prop 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,
  • opacity and backgroundColor,
  • borderRadius, borderWidth and borderColor, also per side and per corner,
  • transform and transformOrigin,
  • boxShadow and the shadow* 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​

Platform compatibility​

AndroidiOSWeb
✅✅❌

On web, SharedTransitionBoundary renders only its children, and shared views show in their places without a transition.