react-native-custom-min-video-player

A React Native video player with a custom control UI and a floating mini player that keeps playback going while users navigate your app.

Built for apps that need a YouTube- or Netflix-style watch experience: inline or fullscreen video, scrubbing, double-tap seek, playback speed, and a draggable mini video player that snaps to the screen edge.

📚 Full guide: docs/CUSTOM_VIDEO_PLAYER_GUIDE.md — installation, architecture, props, wiring API data, customization, and troubleshooting.

Features

• Play / pause / replay
• Scrubbable progress bar with buffer indicator
• Current time & duration
• Loading & error states with retry
• Fullscreen toggle
• Auto-hiding controls + tap to reveal
• Double-tap left/right to seek ±10s
• Playback speed picker
• Poster / thumbnail support
• Resume from timestamp
• Optional background playback
• Floating mini player (drag, snap left/right, play/pause, close)
• Single global player instance (no reload when restoring)

Installation

npm install react-native-custom-min-video-player react-native-video react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-worklets
# or
yarn add react-native-custom-min-video-player react-native-video react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-worklets

Babel

Add Reanimated’s plugin last in babel.config.js:

module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: ['react-native-reanimated/plugin'],
};

Entry file

import 'react-native-gesture-handler';

iOS:

cd ios && pod install && cd ..

Quick start

import {
  VideoPlayer,
  VideoPlayerProvider,
} from 'react-native-custom-min-video-player';

export default function App() {
  return (
    <VideoPlayerProvider
      onRestoreRequest={() => navigation.navigate('Video', lastParams)}
      onFullscreenBack={() => navigation.goBack()}
    >
      {/* Your navigation tree */}
    </VideoPlayerProvider>
  );
}

On a video screen:

<VideoPlayer
  source={{ uri: videoUrl }}
  videoId="unique-id"
  title="Episode 1"
  autoPlay
  enableMiniPlayer
  enableFullscreen
  enableDoubleTap
  enableGestures
  onProgress={({ currentTime, duration }) => {}}
  onEnd={() => {}}
  onError={(message) => {}}
/>

Pressing back (or the in-player back control) does not stop playback — the session collapses into a floating mini player. Tap the mini player to restore fullscreen from the same timestamp.

Close (✕) on the mini player stops playback and releases resources.

Public API

import {
  VideoPlayer,
  VideoPlayerProvider,
  MiniPlayer,
  useVideoPlayer,
  useMiniPlayer,
  VideoPlayerManager,
} from 'react-native-custom-min-video-player';

| Export | Description | |--------|-------------| | VideoPlayerProvider | Hosts the single native Video surface (fullscreen + mini) | | VideoPlayer | Screen helper — opens / restores a session; enables mini on unmount | | MiniPlayer | API stub (UI is rendered by the provider) | | useVideoPlayer | Reactive player state + controls | | useMiniPlayer | Mini visibility helpers | | VideoPlayerManager | Singleton for advance control / cleanup |

Architecture

VideoPlayerProvider
 └─ App navigation
 └─ VideoHost (ONE react-native-video)
      ├─ fullscreen chrome (controls, gestures)
      └─ mini chrome (drag / snap / close)

VideoPlayerManager is the single source of truth for source, position, play state, mode (idle | fullscreen | mini), and errors.

Example app

yarn
yarn example start
yarn example ios
# or
yarn example android

Demo flow: Home → Video → Back → mini player → Browse → tap mini → fullscreen continues.

Peer dependencies

• react, react-native
• react-native-video ≥ 6
• react-native-reanimated ≥ 3
• react-native-gesture-handler ≥ 2.12
• react-native-safe-area-context ≥ 4
• react-native-worklets (required by Reanimated 4)

Publishing

yarn typecheck
yarn prepare   # builds lib/ via react-native-builder-bob
npm publish --access public

License

MIT © Mohammad Ali