Overview
The VideoViewEvents interface defines event callbacks that are triggered by the video view component. These events primarily handle fullscreen and picture-in-picture (PiP) state changes.
Event Categories
Fullscreen
Picture-in-Picture
Events related to fullscreen mode transitions.onFullscreenChange
Called when the video view’s fullscreen state changes.Callback Signature:onFullscreenChange: (fullscreen: boolean) => void
fullscreen - Whether the video view is in fullscreen mode
Example:<Video
source={videoSource}
onFullscreenChange={(isFullscreen) => {
if (isFullscreen) {
console.log('Entered fullscreen mode');
// Lock orientation, hide status bar, etc.
} else {
console.log('Exited fullscreen mode');
// Restore orientation, show status bar, etc.
}
}}
/>
willEnterFullscreen
Called when the video view will enter fullscreen mode.This event fires before the fullscreen transition begins, allowing you to prepare the UI.
willEnterFullscreen: () => void
<Video
source={videoSource}
willEnterFullscreen={() => {
console.log('About to enter fullscreen');
// Prepare UI for fullscreen transition
StatusBar.setHidden(true);
}}
/>
willExitFullscreen
Called when the video view will exit fullscreen mode.This event fires before the fullscreen exit transition begins, allowing you to prepare the UI.
willExitFullscreen: () => void
<Video
source={videoSource}
willExitFullscreen={() => {
console.log('About to exit fullscreen');
// Prepare UI for fullscreen exit
StatusBar.setHidden(false);
}}
/>
Events related to picture-in-picture (PiP) mode transitions.onPictureInPictureChange
Called when the video view’s picture in picture state changes.Callback Signature:onPictureInPictureChange: (isInPictureInPicture: boolean) => void
isInPictureInPicture - Whether the video view is in picture in picture mode
Example:<Video
source={videoSource}
onPictureInPictureChange={(isPiP) => {
if (isPiP) {
console.log('Entered picture-in-picture mode');
// Update UI state
} else {
console.log('Exited picture-in-picture mode');
// Restore UI
}
}}
/>
willEnterPictureInPicture
Called when the video view will enter picture in picture mode.This event fires before the PiP transition begins, allowing you to prepare the UI.
willEnterPictureInPicture: () => void
<Video
source={videoSource}
willEnterPictureInPicture={() => {
console.log('About to enter picture-in-picture');
// Save current state, prepare for PiP
}}
/>
willExitPictureInPicture
Called when the video view will exit picture in picture mode.This event fires before the PiP exit transition begins, allowing you to prepare the UI.
willExitPictureInPicture: () => void
<Video
source={videoSource}
willExitPictureInPicture={() => {
console.log('About to exit picture-in-picture');
// Restore full view state
}}
/>
Event Flow
Fullscreen Transition Flow
Entering Fullscreen:
willEnterFullscreen → (transition) → onFullscreenChange(true)
willExitFullscreen → (transition) → onFullscreenChange(false)
Picture-in-Picture Transition Flow
Entering PiP:
willEnterPictureInPicture → (transition) → onPictureInPictureChange(true)
willExitPictureInPicture → (transition) → onPictureInPictureChange(false)
Complete Example
Here’s a comprehensive example managing both fullscreen and PiP states:
import React, { useState } from 'react';
import { View, Button, StatusBar, Platform } from 'react-native';
import Video from 'react-native-video';
function VideoPlayer() {
const [isFullscreen, setIsFullscreen] = useState(false);
const [isPiP, setIsPiP] = useState(false);
const videoRef = React.useRef(null);
return (
<View style={{ flex: 1 }}>
<Video
ref={videoRef}
source={{ uri: 'https://example.com/video.mp4' }}
// Fullscreen events
willEnterFullscreen={() => {
console.log('Preparing to enter fullscreen');
StatusBar.setHidden(true, 'fade');
}}
onFullscreenChange={(fullscreen) => {
setIsFullscreen(fullscreen);
console.log('Fullscreen state:', fullscreen);
}}
willExitFullscreen={() => {
console.log('Preparing to exit fullscreen');
StatusBar.setHidden(false, 'fade');
}}
// Picture-in-Picture events
willEnterPictureInPicture={() => {
console.log('Preparing to enter PiP');
}}
onPictureInPictureChange={(inPiP) => {
setIsPiP(inPiP);
console.log('PiP state:', inPiP);
}}
willExitPictureInPicture={() => {
console.log('Preparing to exit PiP');
}}
style={{
width: '100%',
height: isFullscreen ? '100%' : 200,
}}
/>
{!isPiP && (
<View>
<Button
title={isFullscreen ? 'Exit Fullscreen' : 'Enter Fullscreen'}
onPress={() => {
if (videoRef.current) {
videoRef.current.setFullscreen(!isFullscreen);
}
}}
/>
{Platform.OS === 'ios' && (
<Button
title="Enter Picture-in-Picture"
onPress={() => {
if (videoRef.current) {
videoRef.current.setPictureInPicture(true);
}
}}
/>
)}
</View>
)}
</View>
);
}
Fullscreen
iOS:
- Fullscreen transitions are handled natively
- Automatically handles status bar visibility
- Supports both landscape and portrait fullscreen
Android:
- May require manual handling of SystemUI visibility
- Consider using
react-native-orientation-locker for orientation control
Picture-in-Picture
iOS:
- Available on iOS 9.0+
- Works on iPad and iPhone (iPhone supports PiP on iOS 14+)
- Automatically pauses when app enters background
Android:
- Available on Android 8.0+ (API level 26+)
- Requires explicit permission in AndroidManifest.xml
- Can continue playing in PiP mode
Picture-in-Picture support varies by platform and OS version. Always check capabilities before enabling PiP features.
Handling Orientation Changes
When entering fullscreen, you may want to lock the orientation:
import Orientation from 'react-native-orientation-locker';
<Video
source={videoSource}
willEnterFullscreen={() => {
Orientation.lockToLandscape();
}}
willExitFullscreen={() => {
Orientation.unlockAllOrientations();
}}
/>
Managing Status Bar
Automatic status bar management during fullscreen transitions:
import { StatusBar } from 'react-native';
<Video
source={videoSource}
willEnterFullscreen={() => {
StatusBar.setHidden(true, 'slide');
}}
onFullscreenChange={(isFullscreen) => {
if (!isFullscreen) {
StatusBar.setHidden(false, 'slide');
}
}}
/>
Best Practices
-
Use
will* events for preparation - Use willEnterFullscreen and willExitFullscreen to prepare the UI before the transition starts
-
Use
on*Change events for state updates - Use onFullscreenChange and onPictureInPictureChange to update your component state
-
Handle cleanup - Always clean up any UI changes (status bar, orientation locks) when exiting fullscreen or PiP
-
Test on both platforms - Fullscreen and PiP behavior differs between iOS and Android
-
Consider user experience - Provide clear visual feedback during transitions
See Also