Skip to main content

​
Overview

The useVideoPlayer hook creates a VideoPlayer instance and manages its lifecycle within a React component. It automatically handles player creation, initialization, and cleanup when the component unmounts.

​
Signature

function useVideoPlayer(
  source: VideoConfig | VideoSource | VideoPlayerSource,
  setup?: (player: VideoPlayer) => void
): VideoPlayer

​
Parameters

​
source
VideoConfig | VideoSource | VideoPlayerSource
required
The source of the video to play. Can be:
  • A string URL (e.g., 'https://example.com/video.mp4')
  • A number from require() (e.g., require('./video.mp4'))
  • A VideoConfig object with additional configuration
  • A VideoPlayerSource Nitro object
​
setup
(player: VideoPlayer) => void
Optional callback function to configure the player after creation. This is where you should:
  • Set initial player properties (volume, muted, loop, etc.)
  • Attach event listeners using player.addEventListener()
  • Configure playback settings
Timing behavior:
  • If initializeOnCreation is true (default): called when the player starts loading the source (on onLoadStart or onStatusChange)
  • If initializeOnCreation is false: called immediately when the player is created
Important: Any changes made to the player before the setup callback runs will be overwritten when initializeOnCreation is true.

​
Return Value

Returns a VideoPlayer instance that can be used to control playback and attach to a VideoView component.

​
Basic Usage

​
Simple Video Player

import { useVideoPlayer } from 'react-native-video';

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

  return <VideoView player={player} style={{ flex: 1 }} />;
}

​
With Setup Callback

import { useVideoPlayer } from 'react-native-video';

function MyVideoPlayer() {
  const player = useVideoPlayer(
    'https://example.com/video.mp4',
    (player) => {
      // Configure initial settings
      player.loop = true;
      player.volume = 0.8;
      player.muted = false;

      // Start playing automatically
      player.play();
    }
  );

  return <VideoView player={player} style={{ flex: 1 }} />;
}

​
With VideoConfig

import { useVideoPlayer } from 'react-native-video';

function MyVideoPlayer() {
  const player = useVideoPlayer(
    {
      uri: 'https://example.com/video.mp4',
      headers: {
        Authorization: 'Bearer token',
      },
      metadata: {
        title: 'My Video',
        artist: 'Video Creator',
      },
      externalSubtitles: [
        {
          uri: 'https://example.com/subtitles_en.vtt',
          label: 'English',
          type: 'vtt',
          language: 'en',
        },
      ],
    },
    (player) => {
      player.play();
    }
  );

  return <VideoView player={player} style={{ flex: 1 }} />;
}

​
Advanced Usage

​
Event Listeners in Setup

import { useVideoPlayer } from 'react-native-video';
import { useState } from 'react';

function MyVideoPlayer() {
  const [duration, setDuration] = useState(0);
  const [currentTime, setCurrentTime] = useState(0);

  const player = useVideoPlayer(
    'https://example.com/video.mp4',
    (player) => {
      // Attach event listeners
      player.addEventListener('onLoad', (data) => {
        setDuration(data.duration);
      });

      player.addEventListener('onProgress', (data) => {
        setCurrentTime(data.currentTime);
      });

      player.addEventListener('onEnd', () => {
        console.log('Video ended');
      });

      // Configure and start playback
      player.loop = true;
      player.play();
    }
  );

  return (
    <View>
      <VideoView player={player} style={{ flex: 1 }} />
      <Text>Progress: {currentTime.toFixed(1)}s / {duration.toFixed(1)}s</Text>
    </View>
  );
}

​
Delayed Initialization

import { useVideoPlayer } from 'react-native-video';
import { useEffect } from 'react';

function MyVideoPlayer() {
  const player = useVideoPlayer(
    {
      uri: 'https://example.com/video.mp4',
      initializeOnCreation: false, // Don't initialize automatically
    },
    (player) => {
      // This runs immediately when player is created
      player.loop = true;
      player.muted = true;
    }
  );

  useEffect(() => {
    // Initialize and start playing when ready
    const initPlayer = async () => {
      await player.initialize();
      player.play();
    };

    initPlayer();
  }, [player]);

  return <VideoView player={player} style={{ flex: 1 }} />;
}

​
VideoConfig Properties

When passing a VideoConfig object as the source:
​
uri
string | number
required
The video URI or local file from require()
​
headers
Record<string, string>
HTTP headers to send with the video request
​
drm
DrmParams
DRM configuration for protected content
​
bufferConfig
BufferConfig
Buffer configuration settings
​
metadata
CustomVideoMetadata
Custom metadata (title, subtitle, description, artist, imageUri) shown in system media controls
​
externalSubtitles
ExternalSubtitle[]
Array of external subtitle tracks
​
initializeOnCreation
boolean
default:"true"
Whether to initialize the native player immediately when created. If false, you must call player.initialize() manually.

​
Notes

  • The hook automatically cleans up the player when the component unmounts
  • The player instance is recreated if the source changes
  • Event listeners added in the setup callback are automatically managed
  • Changes made to the player before the setup callback runs may be overwritten (when initializeOnCreation is true)
  • Use the useEvent hook for adding event listeners that depend on React state or props

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us