rn-floating-video-player

A smooth, draggable floating video player for React Native — with Picture-in-Picture (PiP) mode, full playback controls, edge snapping, and buttery spring animations.

Features

• 🎬 Full-screen video player with all standard controls
• 🪟 Floating mini player (PiP) — drag it anywhere on screen
• 🧲 Edge snapping — mini player snaps to left/right edges on release
• 🎛️ Complete controls — play/pause, seek, volume, mute, skip ±10s, fullscreen
• 💫 Smooth animations — spring physics on drag, fade in/out controls
• 🎨 Themeable — dark/light mode + custom accent color
• 🔧 Imperative API — control the player via ref
• 📱 iOS + Android support

Installation

npm install rn-floating-video-player react-native-video
# or
yarn add rn-floating-video-player react-native-video

iOS

npx pod-install

Android

No extra setup needed beyond react-native-video's own setup.

Usage

Basic

import { FloatingVideoPlayer } from 'rn-floating-video-player';

export default function App() {
  return (
    <FloatingVideoPlayer
      source={{ uri: 'https://example.com/video.mp4' }}
      autoPlay
    />
  );
}

With minimize/maximize

import React, { useState } from 'react';
import { View } from 'react-native';
import { FloatingVideoPlayer } from 'rn-floating-video-player';

export default function App() {
  const [visible, setVisible] = useState(true);

  if (!visible) return null;

  return (
    <View style={{ flex: 1 }}>
      {/* Your app content here */}

      <FloatingVideoPlayer
        source={{ uri: 'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4' }}
        accentColor="#FF6B6B"
        theme="dark"
        autoPlay
        snapToEdge
        onClose={() => setVisible(false)}
        onMinimize={() => console.log('Minimized!')}
        onMaximize={() => console.log('Maximized!')}
        onProgress={(currentTime, duration) => {
          console.log(`${currentTime} / ${duration}`);
        }}
      />
    </View>
  );
}

Using the imperative ref

import React, { useRef } from 'react';
import { Button, View } from 'react-native';
import { FloatingVideoPlayer, FloatingVideoPlayerRef } from 'rn-floating-video-player';

export default function App() {
  const playerRef = useRef<FloatingVideoPlayerRef>(null);

  return (
    <View style={{ flex: 1 }}>
      <FloatingVideoPlayer
        ref={playerRef}
        source={{ uri: 'https://example.com/video.mp4' }}
      />

      <Button title="Play" onPress={() => playerRef.current?.play()} />
      <Button title="Pause" onPress={() => playerRef.current?.pause()} />
      <Button title="Seek to 30s" onPress={() => playerRef.current?.seekTo(30)} />
      <Button title="Minimize" onPress={() => playerRef.current?.minimize()} />
    </View>
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | source | ReactVideoSource | required | Video source (same as react-native-video) | | style | StyleProp<ViewStyle> | — | Container style override | | initialPosition | { x: number, y: number } | Bottom-right | Initial position of mini player | | onMinimize | () => void | — | Called when minimized | | onMaximize | () => void | — | Called when restored | | onClose | () => void | — | Called when close is pressed | | onProgress | (currentTime, duration) => void | — | Playback progress | | onEnd | () => void | — | Video ended | | onError | (error) => void | — | Playback error | | theme | 'dark' \| 'light' | 'dark' | Color theme | | accentColor | string | '#6C63FF' | Progress bar / button color | | autoPlay | boolean | false | Auto-play on mount | | showCloseButton | boolean | true | Show close/dismiss button | | snapToEdge | boolean | true | Mini player snaps to screen edges |

Ref Methods

| Method | Signature | Description | |--------|-----------|-------------| | play | () => void | Play the video | | pause | () => void | Pause the video | | seekTo | (time: number) => void | Seek to time in seconds | | minimize | () => void | Enter PiP/mini mode | | maximize | () => void | Exit PiP/mini mode | | close | () => void | Dismiss the player |

Architecture

src/
├── FloatingVideoPlayer.tsx   # Main component
├── Controls.tsx              # Overlay controls (seekbar, buttons)
├── types.ts                  # TypeScript types & interfaces
├── index.ts                  # Package entry point
└── hooks/
    ├── useVideoState.ts       # Playback state management
    └── useFloatingPosition.ts # Drag, snap, spring physics

Dependencies

• react-native-video — Video playback engine

No other native dependencies required.

License

MIT