Installation

Step-by-step guide to install and configure React Native Video Toolkit in your project.

Requirements

React Native Video Toolkit works with new architecture (Fabric + TurboModules) enabled projects. Ensure you're using React Native 0.76 or higher.

Installation Steps

Install Dependencies

Install the main library along with all required peer dependencies:

npm install react-native-video-toolkit react-native-video react-native-gesture-handler react-native-reanimated react-native-worklets react-native-svg react-native-orientation-director

Make sure to install all dependencies as they are required for the library to function properly.

The toolkit needs react-native-reanimated 4.5 or later (which itself needs React Native 0.83 or later) and react-native-worklets 0.10 or later.

Configure React Native Reanimated

Add the Worklets babel plugin, which Reanimated 4 uses, to your babel.config.js:

module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    'react-native-worklets/plugin', // This should be the last plugin
  ],
};
The Worklets plugin must be listed last in the plugins array.

Configure React Native Gesture Handler

Add the gesture handler configuration to your index.js, App.js , _layout.tsx or equivalent entry file:

import { GestureHandlerRootView } from 'react-native-gesture-handler';

const App = () => <GestureHandlerRootView style={{ flex: 1 }}>{/* Your app content */}</GestureHandlerRootView>;

Wrap Your App

Wrap your app with the required providers:

import React from 'react';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { VideoProvider } from 'react-native-video-toolkit';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <VideoProvider>{/* Your app content */}</VideoProvider>
    </GestureHandlerRootView>
  );
}

Update app.json for screen orientation

If you're using Expo, add the following to your app.json or app.config.js to include the necessary plugin:

{
  "expo": {
    "plugins": ["react-native-orientation-director"]
  }
}

For bare React Native projects, follow the setup instructions in the react-native-orientation-director

Configure react-native-video

If you're using Expo, add the following to your app.json or app.config.js to include the necessary plugin:

{
  "expo": {
    "plugins": [
      [
        "react-native-video",
        {
          "enableNotificationControls": true,
          "enableBackgroundAudio": true,
          "enableAndroidPictureInPicture": true,
          "androidExtensions": {
            "useExoplayerRtsp": false,
            "useExoplayerSmoothStreaming": false,
            "useExoplayerHls": false,
            "useExoplayerDash": false
          }
        }
      ]
    ]
  }
}

enableBackgroundAudio and enableAndroidPictureInPicture are only needed for picture-in-picture.

For bare React Native projects, follow the setup instructions in the react-native-video

Install iOS Dependencies (iOS only)

Install the native pods (the module is autolinked under the New Architecture):

cd ios && pod install

Fullscreen on iOS hides the status bar. For this to take effect, your app's Info.plist must have UIViewControllerBasedStatusBarAppearance set to false. Expo prebuild and the default React Native template usually set this already — add it manually only if the status bar doesn't hide in fullscreen.

For Expo, set it in app.json:

{
  "expo": {
    "ios": {
      "infoPlist": {
        "UIViewControllerBasedStatusBarAppearance": false
      }
    }
  }
}

For bare React Native, add it to ios/<YourApp>/Info.plist:

<key>UIViewControllerBasedStatusBarAppearance</key>
<false/>

Clean and Rebuild

For Expo managed workflow, prebuild your app.

npx expo prebuild

After all this is done, clean your project and rebuild.

# For Android
cd android && ./gradlew clean && cd ..
npx react-native run-android

# For iOS
cd ios && xcodebuild clean && cd ..
npx react-native run-ios

Verification

To verify your installation is working correctly, try importing and using the VideoPlayer component:

import { VideoPlayer, DefaultLayout } from 'react-native-video-toolkit';

export default function TestVideo() {
  return (
    <VideoPlayer
      source={{ uri: 'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4' }}
      style={{ width: '100%', height: 200 }}>
      <DefaultLayout />
    </VideoPlayer>
  );
}

Troubleshooting

Common Issues

Metro bundler errors after installation:

  • Clear Metro cache: npx react-native start --reset-cache
  • Clear node modules: rm -rf node_modules && npm install

Android build errors:

  • Ensure you have the latest Android build tools
  • Try cleaning the Android build: cd android && ./gradlew clean

Gesture handler not working:

  • Make sure you've imported react-native-gesture-handler at the top of your entry file
  • Verify that GestureHandlerRootView wraps your entire app

Getting Help

If you encounter issues:

  1. Check our GitHub Issues
  2. Review the examples
  3. Create a new issue with your specific problem

Introduction

Previous Page

Customization

Next Page

On this page

RequirementsInstallation StepsInstall DependenciesConfigure React Native ReanimatedConfigure React Native Gesture HandlerWrap Your AppUpdate app.json for screen orientationConfigure react-native-videoInstall iOS Dependencies (iOS only)Clean and RebuildVerificationTroubleshootingCommon IssuesGetting Help