Skip to main content
The VideoView component renders video content from a VideoPlayer instance. It provides display controls, fullscreen support, and picture-in-picture functionality.

​
Basic Usage

import { useVideoPlayer, VideoView } from 'react-native-video';
import { View } from 'react-native';

function MyVideo() {
  const player = useVideoPlayer(
    { uri: 'https://example.com/video.mp4' }
  );

  return (
    <VideoView
      player={player}
      style={{ width: '100%', height: 300 }}
    />
  );
}

​
Props

​
player (required)

player: VideoPlayer
The VideoPlayer instance to display. The player controls the video source and playback state. 
const player = useVideoPlayer({ uri: 'https://example.com/video.mp4' });

<VideoView player={player} />

​
style

style?: ViewStyle
The style of the video view. Supports all standard React Native view styles. 
<VideoView
  player={player}
  style={{ width: '100%', height: 300, borderRadius: 10 }}
/>

​
controls

controls?: boolean
Whether to show native video controls. Defaults to false. 
<VideoView player={player} controls={true} />
Native controls vary by platform. iOS uses AVPlayerViewController controls, while Android uses MediaController.

​
resizeMode

resizeMode?: 'contain' | 'cover' | 'stretch' | 'none'
How the video should be resized to fit the view. Defaults to 'none'.
  • 'contain' - Scale uniformly to fit entirely within the view (maintain aspect ratio)
  • 'cover' - Scale uniformly to fill the entire view (maintain aspect ratio, may crop)
  • 'stretch' - Scale to fill the view without maintaining aspect ratio
  • 'none' - Do not resize (fallback to contain behavior)
<VideoView
  player={player}
  resizeMode="cover"
  style={{ width: '100%', height: 300 }}
/>

​
pictureInPicture

pictureInPicture?: boolean
Whether to enable and show the picture-in-picture button in native controls. Defaults to false. 
<VideoView
  player={player}
  controls={true}
  pictureInPicture={true}
/>

​
autoEnterPictureInPicture

autoEnterPictureInPicture?: boolean
Whether to automatically enter picture-in-picture mode when the app moves to background. Defaults to false. 
<VideoView
  player={player}
  pictureInPicture={true}
  autoEnterPictureInPicture={true}
/>

​
keepScreenAwake

keepScreenAwake?: boolean
Whether to keep the screen awake while the video view is mounted. Defaults to true. 
<VideoView player={player} keepScreenAwake={true} />

​
surfaceType

surfaceType?: 'surface' | 'texture'
The type of underlying native view (Android only). Defaults to 'surface'.
  • 'surface' - Uses SurfaceView. More performant, but cannot be animated or transformed
  • 'texture' - Uses TextureView. Less performant, but can be animated and transformed
<VideoView
  player={player}
  surfaceType="texture" // Allows animations on Android
  style={{ transform: [{ scale: 0.8 }] }}
/>
This prop only affects Android. On iOS, it has no effect.

​
Events

​
onFullscreenChange

onFullscreenChange?: (fullscreen: boolean) => void
Called when the video view’s fullscreen state changes. 
<VideoView
  player={player}
  onFullscreenChange={(fullscreen) => {
    console.log('Fullscreen:', fullscreen);
  }}
/>

​
onPictureInPictureChange

onPictureInPictureChange?: (isInPictureInPicture: boolean) => void
Called when the video view’s picture-in-picture state changes. 
<VideoView
  player={player}
  onPictureInPictureChange={(isPip) => {
    console.log('Picture-in-Picture:', isPip);
  }}
/>

​
willEnterFullscreen

willEnterFullscreen?: () => void
Called when the video view is about to enter fullscreen mode. 
<VideoView
  player={player}
  willEnterFullscreen={() => {
    console.log('Will enter fullscreen');
  }}
/>

​
willExitFullscreen

willExitFullscreen?: () => void
Called when the video view is about to exit fullscreen mode. 
<VideoView
  player={player}
  willExitFullscreen={() => {
    console.log('Will exit fullscreen');
  }}
/>

​
willEnterPictureInPicture

willEnterPictureInPicture?: () => void
Called when the video view is about to enter picture-in-picture mode. 
<VideoView
  player={player}
  willEnterPictureInPicture={() => {
    console.log('Will enter PiP');
  }}
/>

​
willExitPictureInPicture

willExitPictureInPicture?: () => void
Called when the video view is about to exit picture-in-picture mode. 
<VideoView
  player={player}
  willExitPictureInPicture={() => {
    console.log('Will exit PiP');
  }}
/>

​
Ref Methods

Use a ref to access imperative methods on the VideoView. 
const videoRef = useRef<VideoViewRef>(null);

<VideoView ref={videoRef} player={player} />

​
enterFullscreen()

enterFullscreen(): void
Enters fullscreen mode. 
videoRef.current?.enterFullscreen();

​
exitFullscreen()

exitFullscreen(): void
Exits fullscreen mode. 
videoRef.current?.exitFullscreen();

​
enterPictureInPicture()

enterPictureInPicture(): void
Enters picture-in-picture mode. 
videoRef.current?.enterPictureInPicture();

​
exitPictureInPicture()

exitPictureInPicture(): void
Exits picture-in-picture mode. 
videoRef.current?.exitPictureInPicture();

​
canEnterPictureInPicture()

canEnterPictureInPicture(): boolean
Checks if picture-in-picture mode is supported and can be entered. 
if (videoRef.current?.canEnterPictureInPicture()) {
  videoRef.current.enterPictureInPicture();
}

​
addEventListener()

addEventListener<Event extends keyof VideoViewEvents>(
  event: Event,
  callback: VideoViewEvents[Event]
): ListenerSubscription
Adds an event listener programmatically. Returns a subscription that can be used to remove the listener. 
const subscription = videoRef.current?.addEventListener(
  'onFullscreenChange',
  (fullscreen) => {
    console.log('Fullscreen changed:', fullscreen);
  }
);

// Later, remove the listener
subscription?.remove();

​
Examples

import { useVideoPlayer, VideoView } from 'react-native-video';
import { View } from 'react-native';

function BasicVideo() {
  const player = useVideoPlayer(
    { uri: 'https://example.com/video.mp4' }
  );

  return (
    <View style={{ flex: 1, justifyContent: 'center' }}>
      <VideoView
        player={player}
        style={{ width: '100%', height: 300 }}
        resizeMode="contain"
      />
    </View>
  );
}

​
Platform Differences

​
iOS

  • Native controls use AVPlayerViewController
  • Picture-in-Picture requires iOS 9+
  • Fullscreen uses native presentation

​
Android

  • Native controls use MediaController
  • Picture-in-Picture requires Android 8.0+ (API 26)
  • surfaceType prop allows choosing between SurfaceView and TextureView
  • TextureView is required for animations and transformations

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us