VideoView

The VideoView component is used to display video content from a VideoPlayer instance. It provides controls for fullscreen, picture-in-picture, and various display options.

Usage

Basic
With Controls
With Ref & Events
Picture in Picture

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

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

  return (
    <VideoView
      player={player}
      style={styles.video}
    />
  );
}

const styles = StyleSheet.create({
  video: {
    width: '100%',
    height: 300,
  },
});

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

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

  return (
    <VideoView
      player={player}
      style={styles.video}
      controls={true}
      pictureInPicture={true}
      resizeMode="contain"
    />
  );
}

const styles = StyleSheet.create({
  video: {
    width: '100%',
    height: 300,
  },
});

import { useRef } from 'react';
import { VideoView, useVideoPlayer, type VideoViewRef } from 'react-native-video';
import { StyleSheet, Button } from 'react-native';

function MyVideoPlayer() {
  const videoViewRef = useRef<VideoViewRef>(null);
  const player = useVideoPlayer(
    { uri: 'https://example.com/video.mp4' },
    (player) => {
      player.play();
    }
  );

  const handleEnterFullscreen = () => {
    videoViewRef.current?.enterFullscreen();
  };

  const handleFullscreenChange = (isFullscreen: boolean) => {
    console.log('Fullscreen:', isFullscreen);
  };

  return (
    <>
      <VideoView
        ref={videoViewRef}
        player={player}
        style={styles.video}
        onFullscreenChange={handleFullscreenChange}
        resizeMode="cover"
      />
      <Button title="Enter Fullscreen" onPress={handleEnterFullscreen} />
    </>
  );
}

const styles = StyleSheet.create({
  video: {
    width: '100%',
    height: 300,
  },
});

import { useRef } from 'react';
import { VideoView, useVideoPlayer, type VideoViewRef } from 'react-native-video';
import { StyleSheet, Button, View } from 'react-native';

function MyVideoPlayer() {
  const videoViewRef = useRef<VideoViewRef>(null);
  const player = useVideoPlayer(
    { uri: 'https://example.com/video.mp4' },
    (player) => {
      player.play();
    }
  );

  const handleEnterPiP = () => {
    if (videoViewRef.current?.canEnterPictureInPicture()) {
      videoViewRef.current.enterPictureInPicture();
    }
  };

  const handlePiPChange = (isInPiP: boolean) => {
    console.log('Picture in Picture:', isInPiP);
  };

  return (
    <View>
      <VideoView
        ref={videoViewRef}
        player={player}
        style={styles.video}
        pictureInPicture={true}
        autoEnterPictureInPicture={false}
        onPictureInPictureChange={handlePiPChange}
      />
      <Button title="Enter PiP" onPress={handleEnterPiP} />
    </View>
  );
}

const styles = StyleSheet.create({
  video: {
    width: '100%',
    height: 300,
  },
});

Props

player

VideoPlayer

required

The VideoPlayer instance to play the video. Create one using useVideoPlayer.

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

style

ViewStyle

The style of the video view. Use React Native’s StyleSheet to define dimensions and other visual properties.

style={{ width: '100%', height: 300 }}

controls

boolean

default:"false"

Whether to show the native playback controls.

controls={true}

pictureInPicture

boolean

default:"false"

Whether to enable and show the picture in picture button in native controls.

pictureInPicture={true}

autoEnterPictureInPicture

boolean

default:"false"

Whether to automatically enter picture in picture mode when the video is playing and the app goes to background.

autoEnterPictureInPicture={true}

resizeMode

'contain' | 'cover' | 'stretch' | 'none'

default:"'none'"

How the video should be resized to fit the view:

'contain': Scale the video uniformly (maintain aspect ratio) so that it fits entirely within the view
'cover': Scale the video uniformly (maintain aspect ratio) so that it fills the entire view (may crop)
'stretch': Scale the video to fill the entire view without maintaining aspect ratio
'none': Do not resize the video - it will fallback to default behavior (contain)

resizeMode="cover"

keepScreenAwake

boolean

default:"true"

Whether to keep the screen awake while the video view is mounted.

keepScreenAwake={true}

surfaceType

'surface' | 'texture'

default:"'surface'"

The type of underlying native view on Android:

'surface': Uses a SurfaceView. More performant, but cannot be animated or transformed.
'texture': Uses a TextureView. Less performant, but can be animated and transformed.

Only applicable on Android.

surfaceType="texture"

Events

onFullscreenChange

(fullscreen: boolean) => void

Called when the video view’s fullscreen state changes.

onFullscreenChange={(fullscreen) => {
  console.log('Is fullscreen:', fullscreen);
}}

onPictureInPictureChange

(isInPictureInPicture: boolean) => void

Called when the video view’s picture in picture state changes.

onPictureInPictureChange={(isInPiP) => {
  console.log('Is in PiP:', isInPiP);
}}

willEnterFullscreen

() => void

Called when the video view will enter fullscreen mode.

willEnterFullscreen={() => {
  console.log('Will enter fullscreen');
}}

willExitFullscreen

() => void

Called when the video view will exit fullscreen mode.

willExitFullscreen={() => {
  console.log('Will exit fullscreen');
}}

willEnterPictureInPicture

() => void

Called when the video view will enter picture in picture mode.

willEnterPictureInPicture={() => {
  console.log('Will enter PiP');
}}

willExitPictureInPicture

() => void

Called when the video view will exit picture in picture mode.

willExitPictureInPicture={() => {
  console.log('Will exit PiP');
}}

Ref Methods

The VideoView component exposes several methods through a ref. Use useRef<VideoViewRef>() to access them.

enterFullscreen

() => void

Enter fullscreen mode.

const videoViewRef = useRef<VideoViewRef>(null);

// Later...
videoViewRef.current?.enterFullscreen();

exitFullscreen

() => void

Exit fullscreen mode.

const videoViewRef = useRef<VideoViewRef>(null);

// Later...
videoViewRef.current?.exitFullscreen();

enterPictureInPicture

() => void

Enter picture in picture mode.

const videoViewRef = useRef<VideoViewRef>(null);

// Later...
videoViewRef.current?.enterPictureInPicture();

exitPictureInPicture

() => void

Exit picture in picture mode.

const videoViewRef = useRef<VideoViewRef>(null);

// Later...
videoViewRef.current?.exitPictureInPicture();

canEnterPictureInPicture

() => boolean

Check if picture in picture mode is supported on the current device.Returns true if picture in picture mode is supported, false otherwise.

const videoViewRef = useRef<VideoViewRef>(null);

// Later...
if (videoViewRef.current?.canEnterPictureInPicture()) {
  videoViewRef.current.enterPictureInPicture();
}

addEventListener

<Event extends keyof VideoViewEvents>(event: Event, callback: VideoViewEvents[Event]) => ListenerSubscription

Adds a listener for a view event. Returns a subscription object that can be used to remove the listener.Available events:

onPictureInPictureChange
onFullscreenChange
willEnterFullscreen
willExitFullscreen
willEnterPictureInPicture
willExitPictureInPicture

const videoViewRef = useRef<VideoViewRef>(null);

useEffect(() => {
  const subscription = videoViewRef.current?.addEventListener(
    'onFullscreenChange',
    (fullscreen) => {
      console.log('Fullscreen changed:', fullscreen);
    }
  );

  return () => {
    subscription?.remove();
  };
}, []);

VideoPlayer - The player instance that controls video playback
useVideoPlayer - Hook to create and manage a VideoPlayer instance
useEvent - Hook to listen to player events

Components

Classes

Hooks

Types

Events

Usage

Props

player

style

controls

pictureInPicture

autoEnterPictureInPicture

resizeMode

keepScreenAwake

surfaceType

Events

onFullscreenChange

onPictureInPictureChange

willEnterFullscreen

willExitFullscreen

willEnterPictureInPicture

willExitPictureInPicture

Ref Methods

enterFullscreen

exitFullscreen

enterPictureInPicture

exitPictureInPicture

canEnterPictureInPicture

addEventListener

Build docs developers (and LLMs) love

Components

Classes

Hooks

Types

Events

​Usage

​Props

​player

​style

​controls

​pictureInPicture

​autoEnterPictureInPicture

​resizeMode

​keepScreenAwake

​surfaceType

​Events

​onFullscreenChange

​onPictureInPictureChange

​willEnterFullscreen

​willExitFullscreen

​willEnterPictureInPicture

​willExitPictureInPicture

​Ref Methods

​enterFullscreen

​exitFullscreen

​enterPictureInPicture

​exitPictureInPicture

​canEnterPictureInPicture

​addEventListener

​Related

Build docs developers (and LLMs) love

Usage

Props

player

style

controls

pictureInPicture

autoEnterPictureInPicture

resizeMode

keepScreenAwake

surfaceType

Events

onFullscreenChange

onPictureInPictureChange

willEnterFullscreen

willExitFullscreen

willEnterPictureInPicture

willExitPictureInPicture

Ref Methods

enterFullscreen

exitFullscreen

enterPictureInPicture

exitPictureInPicture

canEnterPictureInPicture

addEventListener

Related