Skip to main content

​
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:
PackageMinimum 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-contextAny version
Using older versions of these dependencies may cause compatibility issues or runtime errors.

​
Configure React Native Reanimated

Add the Reanimated plugin to your Babel configuration:
1

Edit babel.config.js

Open your babel.config.js file and add the plugin:
babel.config.js
module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    'react-native-reanimated/plugin',
  ],
};
The Reanimated plugin must be listed last in your plugins array.
2

Clear Metro cache

After adding the plugin, clear your Metro bundler cache:
npx react-native start --reset-cache

​
Configure Gesture Handler (iOS)

For iOS, wrap your app entry point with GestureHandlerRootView:

​
React Navigation

App.tsx
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

app/_layout.tsx
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>
  );
}
If this renders without errors, your installation is complete!

​
Next Steps

Quick Start

Create your first custom transition

API Reference

Explore all available options and components