The root component of the toolkit that provides video playback, gesture handling, and a flexible API for composing custom control layouts.

VideoPlayer

The VideoPlayer is the root component of the toolkit.
It provides video playback, gesture handling, and a flexible API for composing custom control layouts.

This component uses a compound component pattern:

<VideoPlayer>
  <VideoPlayer.Controls>
    <VideoPlayer.PlayButton />
    <VideoPlayer.ProgressBar />
    <VideoPlayer.TimeDisplay />
  </VideoPlayer.Controls>
</VideoPlayer>

Usage

import { VideoPlayer } from 'react-native-video-toolkit';

export default function App() {
  return (
    <VideoPlayer source={{ uri: 'https://example.com/video.mp4' }} videoProps={{ resizeMode: 'contain' }}>
      <VideoPlayer.Controls>
        <VideoPlayer.PlayButton />
        <VideoPlayer.ProgressBar />
        <VideoPlayer.TimeDisplay />
        <VideoPlayer.VolumeControl />
        <VideoPlayer.FullscreenButton />
        <VideoPlayer.SettingsButton />
      </VideoPlayer.Controls>
      <VideoPlayer.Menu />
    </VideoPlayer>
  );
}

Props

Prop	Type	Required	Default	Description
`source`	`VideoSource`	Yes	–	Video source (`uri`, local file, or require). Extends `react-native-video`.
`children`	`ReactNode`	No	–	Optional custom overlay or controls.
`containerStyle`	`StyleProp<ViewStyle>`	No	–	Style applied to the root container.
`videoProps`	`ReactVideoProps`	No	–	Props passed to the underlying `react-native-video` player.
`gestureProps`	`GestureHandlerProps`	No	–	Props for the built-in `GestureHandler` (e.g. double-tap to seek).
`videoStyle`	`StyleProp<ViewStyle>`	No	–	Style applied to the video component.
`customAudioTracks`	`AudioTrack[]`	No	–	Custom audio tracks to use when `config.useCustomAudioTracks` is `true`.
`customVideoTracks`	`VideoTrack[]`	No	–	Custom video tracks to use when `config.useCustomVideoTracks` is `true`.

Examples

Minimal Player

<VideoPlayer source={{ uri: 'https://example.com/video.mp4' }}>
  <DefaultLayout />
</VideoPlayer>

With Custom Controls

<VideoPlayer source={{ uri: 'https://example.com/video.mp4' }}>
  <VideoPlayer.Controls style={{ justifyContent: 'space-between' }}>
    <VideoPlayer.PlayButton />
    <VideoPlayer.ProgressBar />
    <VideoPlayer.TimeDisplay />
  </VideoPlayer.Controls>
</VideoPlayer>

With Custom Tracks

import type { AudioTrack, VideoTrack } from 'react-native-video';

const audioTracks: AudioTrack[] = [
  { index: 0, title: 'English', language: 'en', type: 'audio/mp4a-latm' },
  { index: 1, title: 'Spanish', language: 'es', type: 'audio/mp4a-latm' },
];

const videoTracks: VideoTrack[] = [
  { index: 0, width: 1920, height: 1080, bitrate: 5000000, codecs: 'avc1.640028' },
  { index: 1, width: 1280, height: 720, bitrate: 2500000, codecs: 'avc1.640028' },
];

<VideoProvider config={{ useCustomAudioTracks: true, useCustomVideoTracks: true }}>
  <VideoPlayer
    source={{ uri: 'https://example.com/video.m3u8' }}
    customAudioTracks={audioTracks}
    customVideoTracks={videoTracks}>
    <DefaultLayout />
  </VideoPlayer>
</VideoProvider>;

Compound Components

The VideoPlayer exports several prebuilt UI primitives:

Component	Description
`VideoPlayer.Controls`	A container for grouping controls (`absoluteFill`).
`VideoPlayer.PlayButton`	Toggles play/pause.
`VideoPlayer.ProgressBar`	Displays seekable progress.
`VideoPlayer.TimeDisplay`	Shows current time / duration.
`VideoPlayer.VolumeControl`	Slider for adjusting volume.
`VideoPlayer.FullscreenButton`	Toggles fullscreen.
`VideoPlayer.MuteButton`	Toggles mute on/off.
`VideoPlayer.LoadingSpinner`	Spinner for buffering state.
`VideoPlayer.SettingsButton`	Opens settings menu.
`VideoPlayer.Menu`	Bottom-sheet style menu for settings.

The layout automatically adapts when toggling fullscreen (height/width swap based on device orientation). - All controls are theme-aware (colors, sizes come from useVideo provider). - If you don't like the built-in controls, you can compose your own using the hooks and providers.

VideoPlayer

On this page