Migrating to v7

Complete guide to migrating from React Native Video v6 to v7

Migrating from v6 to v7

Version 7 of React Native Video introduces a significant architectural shift, separating the video player logic from UI rendering. This change unlocks new capabilities like video preloading, better performance, and a more intuitive hook-based API.

Breaking Changes Ahead

Version 7 includes substantial breaking changes:

• Complete API redesign with new components and hooks
• New dependency on react-native-nitro-modules
• Minimum React Native version raised to 0.75.0
• Different prop and method names
• New event handling system

What’s New in v7

Nitro Modules Architecture

v7 is built on top of react-native-nitro-modules, a modern framework that provides:

• Type-safety: Full TypeScript support with native type checking
• Performance: Blazing fast communication between Native and JavaScript threads
• Modern Architecture: Full support for React Native’s New Architecture
• Better Developer Experience: Improved error handling and debugging

Component Separation

The monolithic <Video> component is now split into:

• VideoPlayer: A class that manages player state and playback logic (not a UI component)
• VideoView: A UI component that renders the video on screen
• useVideoPlayer hook: Recommended way to create and manage VideoPlayer lifecycle
• useEvent hook: Standardized event handling with automatic cleanup

Key Benefits

• Video Preloading: Create player instances before displaying them
• Better Performance: Separation of concerns improves rendering efficiency
• Cleaner API: Hook-based API reduces boilerplate code
• Multiple Players: Easier management of multiple video players
• Picture-in-Picture: Enhanced PiP support for multiple videos

Requirements

System Requirements

• iOS 15.0 or higher
• Android 6.0 or higher

Package Requirements

• React Native 0.75.0 or higher
• react-native-nitro-modules 0.27.2 or higher (recommended 0.31.10+)

React Native < 0.80

Versions below 0.80 have a bug preventing proper error handling on Android. Apply the react-native-nitro-modules patch documented in the Installation guide.

Migration Steps

1. Install New Dependencies

   First, install the new dependencies. Note that v7 requires react-native-nitro-modules:

   npm install react-native-video@beta react-native-nitro-modules
   

   For iOS, install pods:

   cd ios && pod install
   
2. Update Imports

   Change your imports from the old Video component to the new API:

   v6:

   import Video from 'react-native-video';
   

   v7:

   import { useVideoPlayer, VideoView, useEvent } from 'react-native-video';
   
3. Replace Component Structure

   Replace the <Video> component with useVideoPlayer hook and <VideoView> component.

   v6 Example:

   import React, { useRef } from 'react';
   import Video from 'react-native-video';
   
   const VideoPlayerV6 = () => {
     const videoRef = useRef(null);
   
     return (
       <Video
         source={{ uri: 'https://www.w3schools.com/html/mov_bbb.mp4' }}
         ref={videoRef}
         style={{ width: 300, height: 200 }}
         controls={true}
         paused={false}
         muted={false}
         volume={1.0}
         rate={1.0}
         resizeMode="contain"
         onLoad={() => console.log('Video loaded')}
         onProgress={(data) => console.log('Progress:', data.currentTime)}
         onError={(error) => console.error('Error:', error)}
       />
     );
   };
   

   v7 Example:

   import React from 'react';
   import { useVideoPlayer, VideoView, useEvent } from 'react-native-video';
   
   const VideoPlayerV7 = () => {
     const player = useVideoPlayer({
       source: {
         uri: 'https://www.w3schools.com/html/mov_bbb.mp4',
       },
       // Player configuration
       paused: false,
       muted: false,
       volume: 1.0,
       rate: 1.0,
     });
   
     useEvent(player, 'onLoad', () => {
       console.log('Video loaded');
     });
   
     useEvent(player, 'onProgress', (data) => {
       console.log('Progress:', data.currentTime);
     });
   
     useEvent(player, 'onError', (error) => {
       console.error('Error:', error.code, error.message);
     });
   
     return (
       <VideoView
         player={player}
         style={{ width: 300, height: 200 }}
         controls={true}
         resizeMode="contain"
       />
     );
   };
   
4. Migrate Props

   Move props to their new locations. Some props stay on <VideoView>, while others move to the VideoPlayer configuration.

   Props on VideoView (UI-related)

   • style
   • controls
   • resizeMode

   Props on VideoPlayer (Playback-related)

   All playback-related props are now configured in useVideoPlayer or set directly on the player instance:

   • source
   • paused
   • muted
   • volume
   • rate
   • loop
   • And more…

   See the VideoPlayer documentation for complete details.

5. Update Method Calls

   Methods previously called on the component ref are now on the VideoPlayer instance.

   v6:

   const videoRef = useRef(null);
   
   // Later in code
   videoRef.current.seek(30);
   videoRef.current.pause();
   videoRef.current.presentFullscreenPlayer();
   

   v7:

   const player = useVideoPlayer({ source: { uri: '...' } });
   const videoViewRef = useRef(null);
   
   // Later in code
   player.seekTo(30);
   player.pause();
   videoViewRef.current?.enterFullscreen();
   

   Fullscreen methods are now on the VideoView ref, not the player instance.

6. Migrate Event Handlers

   Event handling is now standardized through the useEvent hook or direct callback assignment.

   Using useEvent (Recommended):

   const player = useVideoPlayer({ source: { uri: '...' } });
   
   useEvent(player, 'onLoad', (data) => {
     console.log('Duration:', data.duration);
   });
   
   useEvent(player, 'onProgress', (data) => {
     console.log('Current time:', data.currentTime);
   });
   

   Direct Assignment:

   const player = useVideoPlayer('https://example.com/video.mp4', (_player) => {
     _player.onLoad = (data) => {
       console.log('Video loaded! Duration:', data.duration);
     };
     _player.onError = (error) => {
       console.error('Player Error:', error.code, error.message);
     };
   });
   

   See the Events documentation for all available events.

Breaking Changes Reference

Component Changes

v6	v7	Notes
<Video />	<VideoView player={player} />	Complete redesign
ref={videoRef}	Separate: player for playback, ref for VideoView	Fullscreen methods on VideoView ref

Props Migration

v6 Prop (<Video>)	v7 Equivalent	Location
source	source	useVideoPlayer config
paused	paused	Player property or config
muted	muted	Player property or config
volume	volume	Player property or config
rate	rate	Player property or config
loop	loop	Player property or config
resizeMode	resizeMode	<VideoView> prop
controls	controls	<VideoView> prop

Methods Migration

v6 Method	v7 Method	Location
videoRef.current.seek(time)	player.seekTo(time)	Player instance
videoRef.current.pause()	player.pause()	Player instance
videoRef.current.resume()	player.play()	Player instance
videoRef.current.presentFullscreenPlayer()	videoViewRef.current.enterFullscreen()	VideoView ref
videoRef.current.dismissFullscreenPlayer()	videoViewRef.current.exitFullscreen()	VideoView ref

Event Handling

v6 Event	v7 Event	Handling
onLoad	onLoad	useEvent hook or direct assignment
onProgress	onProgress	useEvent hook or direct assignment
onError	onError	useEvent hook or direct assignment
All events as props	All events via hooks	More consistent and cleaner

Advanced Features

Video Preloading

One of the major benefits of v7 is the ability to preload videos:

const PlaylistPlayer = () => {
  // Create multiple players
  const player1 = useVideoPlayer({ source: { uri: 'video1.mp4' } });
  const player2 = useVideoPlayer({ source: { uri: 'video2.mp4' } });
  const player3 = useVideoPlayer({ source: { uri: 'video3.mp4' } });

  const [currentPlayer, setCurrentPlayer] = useState(player1);

  return (
    <View>
      <VideoView player={currentPlayer} style={styles.video} />
      <Button title="Next Video" onPress={() => {
        setCurrentPlayer(player2); // Instant switch!
      }} />
    </View>
  );
};

Multiple Video Players

Managing multiple players is now much cleaner:

const MultiVideoScreen = () => {
  const player1 = useVideoPlayer({ source: { uri: 'video1.mp4' } });
  const player2 = useVideoPlayer({ source: { uri: 'video2.mp4' } });

  return (
    <View>
      <VideoView player={player1} style={styles.video1} />
      <VideoView player={player2} style={styles.video2} />
    </View>
  );
};

Troubleshooting

TypeScript Errors

If you encounter TypeScript errors, ensure you have the latest type definitions:

npm install --save-dev @types/react @types/react-native

Android Error Handling

For React Native < 0.80, apply the nitro modules patch to ensure proper error handling on Android. See the Installation guide.

Build Errors on iOS

If you encounter build errors after upgrading:

cd ios
rm -rf Pods Podfile.lock build
pod install
cd ..
npx react-native run-ios

Build Errors on Android

Clean and rebuild:

cd android
./gradlew clean
cd ..
npx react-native run-android

Need Help?

• Check the full documentation
• Join the Discord community
• Review example code
• Contact TWG for professional support

Version Support

Version	Status	Architecture	Support
v5 and lower	End-of-life	Old Architecture	Commercial only
v6	Maintained	Old + New (Interop)	Community + TWG
v7	Active Development	Old + New (Full)	Active