Documentation Index
Fetch the complete documentation index at: https://mintlify.com/TheWidlarzGroup/react-native-video/llms.txt
Use this file to discover all available pages before exploring further.
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