Install the Package
Install react-native-screen-transitions using your package manager:
npm install react-native-screen-transitions
Install Peer Dependencies
The library requires several peer dependencies to function. Install all of them:
npm install react-native-reanimated react-native-gesture-handler \
@react-navigation/native @react-navigation/native-stack \
@react-navigation/elements react-native-screens \
react-native-safe-area-context
Required Versions
Ensure your peer dependencies meet these minimum version requirements:
| Package | Minimum Version |
|---|
react-native-reanimated | ≥3.16.0 or ≥4.0.0 |
react-native-gesture-handler | ≥2.16.1 |
@react-navigation/native | ≥6.0.0 |
@react-navigation/native-stack | ≥7.0.0 |
@react-navigation/elements | ≥2.0.0 |
react-native-screens | ≥4.4.0 |
react-native-safe-area-context | Any version |
Using older versions of these dependencies may cause compatibility issues or runtime errors.
Edit babel.config.js
Open your babel.config.js file and add the plugin:module.exports = {
presets: ['module:@react-native/babel-preset'],
plugins: [
'react-native-reanimated/plugin',
],
};
The Reanimated plugin must be listed last in your plugins array.
Clear Metro cache
After adding the plugin, clear your Metro bundler cache:npx react-native start --reset-cache
GestureHandlerRootView:
React Navigation
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { NavigationContainer } from '@react-navigation/native';
export default function App() {
return (
<GestureHandlerRootView style={{ flex: 1 }}>
<NavigationContainer>
{/* Your navigation setup */}
</NavigationContainer>
</GestureHandlerRootView>
);
}
Expo Router
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { Stack } from 'expo-router';
export default function RootLayout() {
return (
<GestureHandlerRootView style={{ flex: 1 }}>
<Stack>
{/* Your screens */}
</Stack>
</GestureHandlerRootView>
);
}
Optional: Masked View (for Shared Element Presets)
If you plan to use the Instagram or Apple Music shared element presets, install the masked view library:
npx expo install @react-native-masked-view/masked-view
Masked View requires native code and will not work in Expo Go. You’ll need to use a development build or EAS Build.
Verify Installation
Test your installation by creating a simple stack navigator:
import { createBlankStackNavigator } from 'react-native-screen-transitions/blank-stack';
import { View, Text } from 'react-native';
const Stack = createBlankStackNavigator();
function HomeScreen() {
return (
<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
<Text>Home Screen</Text>
</View>
);
}
export default function App() {
return (
<Stack.Navigator>
<Stack.Screen name="Home" component={HomeScreen} />
</Stack.Navigator>
);
}
Next Steps
Quick Start
Create your first custom transition
API Reference
Explore all available options and components
