@streamspark/react-video-player

🎥 @streamspark/react-video-player

A fully-featured, YouTube-like video player built completely from scratch using React and TypeScript — no third-party video libraries involved.

Perfect for developers looking for a clean, minimal, extensible, and dependency-free media player.

✅ Features

• 🎬 Custom play/pause/seek controls (with buffer indicator)
• 🔊 Volume control with mute & smooth slider behavior
• ⏩ Live seek drag - YouTube-style real-time scrubbing
• 📺 Fullscreen toggle
• 🌐 Subtitle (.vtt) support
• 📝 Custom draggable captions with full styling control
• ⚙️ Playback speed control (0.25x – 2x)
• 🌓 Light & dark themes
• 📱 Fully responsive layout & mobile touch support
• 🎮 YouTube-style keyboard shortcuts
• ♿ Accessible (ARIA & screen reader friendly)
• 🎨 Complete control customization - show/hide and style any control
• 🎨 Themeable via CSS variables
• 🧱 No 3rd-party libraries – pure React

✨ What's New

⏩ Live Seek Drag (NEW!)

• YouTube-style scrubbing - drag the seek bar thumb for real-time seeking
• Live video preview - see video content as you drag through the timeline
• Smooth interaction - no delay between drag and video response
• Cross-platform support - works on both desktop and mobile devices
• Enhanced visual feedback - thumb grows during drag for better grip
• Touch-friendly - optimized for finger dragging on mobile devices

📝 Custom Draggable Captions (NEW!)

• Fully customizable captions with complete styling control
• Drag & drop positioning - move captions anywhere on the video
• YouTube-like styling - clean, unobtrusive appearance
• Mobile touch support - drag with finger on mobile devices
• Boundary constraints - captions stay within video player bounds
• Timing control - precise start/end times for each caption
• Visual feedback - hover effects and drag indicators

🧠 Smarter Control Visibility

• Controls remain visible while mouse is anywhere inside the player
• Hide only when mouse leaves — like YouTube
• No flickering or premature hide during interaction

🔊 Volume Panel (Improved UX)

• Click to open — no accidental hover changes
• Auto hides when mouse leaves the panel
• Smooth sliding and clear mute indicator

🎞️ Seek Bar Preview (Optional)

• Integrated <canvas> + <video> thumbnail preview
• Works with sprite images or auto-generated previews
• Fast and optimized

📷 Instant Thumbnail Preview (Optional)

• Hover previews powered by <video> + <canvas>.
• Works with both sprite frames and per-second captures.
• Fully optimized for performance — previews load instantly.

🎨 Complete Control Customization (NEW!)

• Full control visibility - show/hide any control individually
• Complete styling control - customize every aspect of the player's appearance
• Button styles - customize play, volume, and all control buttons
• Seek bar customization - control colors, sizes, and hover effects
• Volume slider styling - customize width, colors, and thumb appearance
• Time display styling - control fonts, colors, backgrounds, and effects
• Menu customization - style playback speed, quality, and share menus
• Tooltip styling - customize tooltip appearance and delays
• CSS variables support - use CSS variables for advanced customization
• TypeScript interfaces - full type safety for all customization options

🚀 Live Demo

Try it online (no setup required):
👉 StackBlitz Demo

🔗 Links

🔧 GitHub: https://github.com/arun59ay/react-video-player

📦 NPM: https://www.npmjs.com/package/react-smart-video-player

⚡ Live Demo: https://stackblitz.com/github/arun59ay/react-video-player

📦 Installation

npm install react-video-player

You also need to import the default styles manually:

import 'react-video-player/dist/index.css';


import React from 'react';
import { VideoPlayer } from 'react-video-player';
import 'react-video-player/dist/index.css';

export default function App() {
  return (
    <VideoPlayer
      src="/videos/sample.mp4"
      poster="/images/thumb.jpg"
      title="Demo Player"
      theme="dark"
    />
  );
}

### 📝 Custom Draggable Captions

```tsx
import React from 'react';
import { VideoPlayer } from 'react-video-player';
import { CaptionConfig } from 'react-video-player';

const customCaptions: CaptionConfig[] = [
  {
    text: "🎬 Welcome to our video!",
    startTime: 0,
    endTime: 5,
    style: {
      fontSize: '16px',
      color: '#ffffff',
      backgroundColor: 'rgba(0, 0, 0, 0.8)',
      position: 'bottom',
      padding: '8px 12px',
      borderRadius: '4px',
      fontWeight: 'bold'
    }
  },
  {
    text: "📱 Drag me anywhere!",
    startTime: 5,
    endTime: 10,
    style: {
      fontSize: '14px',
      color: '#ff6b6b',
      backgroundColor: 'rgba(255, 107, 107, 0.9)',
      position: 'top',
      padding: '6px 10px',
      borderRadius: '6px',
      textAlign: 'center'
    }
  }
];

const App = () => (
  <VideoPlayer
    src="/videos/sample.mp4"
    customCaptions={customCaptions}
    title="Custom Captions Demo"
    theme="dark"
    width="100%"
    height="400px"
  />
);

CaptionConfig Interface:

interface CaptionConfig {
  text: string;                    // Caption text content
  startTime: number;               // Start time in seconds
  endTime: number;                 // End time in seconds
  style?: {
    fontSize?: string;             // Font size (e.g., '16px')
    fontFamily?: string;           // Font family
    color?: string;                // Text color
    backgroundColor?: string;      // Background color
    padding?: string;              // Padding (e.g., '8px 12px')
    borderRadius?: string;         // Border radius
    textAlign?: 'left' | 'center' | 'right';
    position?: 'bottom' | 'top';   // Default position
    margin?: string;               // Margin
    opacity?: number;              // Opacity (0-1)
    textShadow?: string;           // Text shadow
    fontWeight?: string | number;   // Font weight
    lineHeight?: string;           // Line height
    maxWidth?: string;             // Max width
    wordWrap?: 'break-word' | 'normal';
    zIndex?: number;               // Z-index
    border?: string;               // Border
    boxShadow?: string;            // Box shadow
  };
}

Features:

• ✅ Drag & Drop: Click and drag captions anywhere on the video
• ✅ Mobile Touch: Touch and drag on mobile devices
• ✅ Boundary Constraints: Captions stay within video player bounds
• ✅ Visual Feedback: Hover effects and drag indicators
• ✅ Position Memory: Captions remember their position after dragging
• ✅ Full Styling: Complete control over appearance and positioning

⏩ Live Seek Drag

The video player includes YouTube-style live seek dragging for smooth video scrubbing:

import React from 'react';
import { VideoPlayer } from 'react-video-player';

const App = () => (
  <VideoPlayer
    src="/videos/sample.mp4"
    title="Live Seek Demo"
    // Live seek drag is enabled by default
    // Just drag the seek bar thumb to scrub through the video
  />
);

Live Seek Features:

• ✅ Real-time Scrubbing: Drag the seek bar thumb to jump through video
• ✅ Live Preview: See video content as you drag through the timeline
• ✅ Smooth Interaction: No delay between drag and video response
• ✅ Cross-platform: Works on both desktop and mobile devices
• ✅ Enhanced Feedback: Thumb grows during drag for better grip
• ✅ Touch Optimized: Finger-friendly dragging on mobile devices

📝 Basic Usage Example

import React from 'react';
import { VideoPlayer } from 'react-video-player';
import 'react-video-player/dist/index.css';

const App = () => (
  <VideoPlayer
    src="/videos/sample.mp4"
    poster="/images/thumb.jpg"
    captions="/captions/subtitles.vtt"
    title="Advanced Demo Player"
    theme="light"
    autoplay={false}
    loop={false}
    muted={false}
    controls={true}
    width="800px"
    height="450px"
    className="my-custom-player"
    style={{ borderRadius: '12px' }}
    onPlay={() => console.log('Video started')}
    onPause={() => console.log('Video paused')}
    onTimeUpdate={(time) => console.log('Time:', time)}
    onVolumeChange={(vol) => console.log('Volume:', vol)}
    onSeek={(time) => console.log('Seeked to:', time)}
    onEnded={() => console.log('Ended')}
    onError={(err) => console.error('Error:', err)}
  />
);

🎮 Keyboard Shortcuts

Action	Keys
Play / Pause	Space / K
Seek -10s	← / J
Seek +10s	→ / L
Volume Up	↑
Volume Down	↓
Mute / Unmute	M
Fullscreen Toggle	F
Speed Down	Shift + ,
Speed Up	Shift + .
Go to Start	Home
Go to End	End

📋 Props API

Basic Props

Prop	Type	Default	Description
src	string | string[] | PlaylistItem[]	— (req)	Video source URL(s) or playlist
poster	string	undefined	Poster image
captions	string | SubtitleTrack[]	undefined	WebVTT subtitles file or array
customCaptions	CaptionConfig[]	undefined	Custom draggable captions array
title	string	undefined	Accessible title for screen readers
description	string	undefined	Video description
theme	'light' | 'dark'	'dark'	UI Theme
autoplay	boolean	false	Autoplay on load
loop	boolean	false	Loop the video
muted	boolean	false	Mute by default
controls	boolean	true	Show/hide player controls
width	string | number	'100%'	Custom player width
height	string | number	'auto'	Custom player height
className	string	''	Custom class for the wrapper
style	React.CSSProperties	{}	Inline styles

Advanced Props

Prop	Type	Default	Description
chapters	Chapter[]	undefined	Video chapters array
qualities	VideoQuality[]	undefined	Video quality options
enablePictureInPicture	boolean	true	Enable Picture-in-Picture mode
enableTheaterMode	boolean	true	Enable Theater mode
enableAnalytics	boolean	false	Enable analytics tracking
enableSocialShare	boolean	true	Enable social sharing
enableKeyboardShortcuts	boolean	true	Enable keyboard shortcuts
showKeyboardShortcutsHelp	boolean	false	Show keyboard shortcuts help
theaterMode	boolean	false	Initial theater mode state
controlOptions	ControlOptions	undefined	Control customization options

🧠 Event Callbacks

Callback	Type	Description
onPlay	() => void	Triggered when playback starts
onPause	() => void	Triggered when paused
onTimeUpdate	(time: number) => void	On time change during playback
onVolumeChange	(volume: number) => void	On volume update
onSeek	(time: number) => void	When seeking is done
onEnded	() => void	When video ends
onError	(error: string) => void	If video load/playback fails
onChapterChange	(chapter: Chapter) => void	When chapter changes
onQualityChange	(quality: string) => void	When quality changes
onSubtitleChange	(language: string) => void	When subtitle language changes
onPlaylistItemChange	(index: number, item: PlaylistItem) => void	When playlist item changes
onAnalyticsUpdate	(data: AnalyticsData) => void	Analytics data update
onShare	(timestamp?: number) => void	When video is shared

🎨 Customization

The video player offers extensive customization options through the controlOptions prop, allowing you to control visibility, styling, and behavior of all controls.

Control Options

The controlOptions prop provides complete control over the player's appearance and functionality:

import { VideoPlayer, ControlOptions } from 'react-video-player';

const controlOptions: ControlOptions = {
  // Visibility toggles
  showPlayButton: true,
  showVolumeControl: true,
  showTimeDisplay: true,
  showSeekBar: true,
  showPlaybackSpeed: true,
  showQualitySelector: true,
  showCaptionsButton: true,
  showFullscreenButton: true,
  showPictureInPictureButton: true,
  showTheaterModeButton: true,
  showSocialShare: true,
  showChapterMarkers: true,

  // Button styles
  playButtonStyle: {
    backgroundColor: 'rgba(0, 0, 0, 0.5)',
    hoverBackgroundColor: 'rgba(0, 0, 0, 0.9)',
    color: 'white',
    borderRadius: '50%',
    width: '48px',
    height: '48px'
  },

  volumeButtonStyle: {
    backgroundColor: 'rgba(0, 0, 0, 0.5)',
    hoverBackgroundColor: 'rgba(0, 0, 0, 0.7)',
    color: 'white',
    borderRadius: '50%'
  },

  controlButtonStyle: {
    backgroundColor: 'transparent',
    hoverBackgroundColor: 'rgba(255, 255, 255, 0.2)',
    color: 'white',
    padding: '8px',
    width: '44px',
    height: '44px'
  },

  // Seek bar styles
  seekBarStyle: {
    height: '8px',
    hoverHeight: '14px',
    backgroundColor: 'rgba(255, 255, 255, 0.3)',
    playedColor: '#ff0000',
    bufferedColor: 'rgba(255, 255, 255, 0.4)',
    thumbColor: '#ff0000',
    thumbSize: '16px',
    hoverThumbSize: '22px',
    borderRadius: '4px'
  },

  // Volume slider styles
  volumeSliderStyle: {
    width: '120px',
    height: '44px',
    backgroundColor: 'transparent',
    fillColor: '#ff0000',
    thumbColor: 'white',
    thumbSize: '14px',
    borderRadius: '22px'
  },

  // Time display styles
  timeDisplayStyle: {
    fontSize: '14px',
    fontWeight: 500,
    color: 'white',
    backgroundColor: 'rgba(0, 0, 0, 0.5)',
    backdropFilter: 'blur(10px) saturate(180%)',
    borderColor: 'rgba(255, 255, 255, 0.1)',
    borderRadius: '4px',
    padding: '4px 8px',
    textShadow: '0 1px 2px rgba(0, 0, 0, 0.8)'
  },

  // Controls bar styles
  controlsBarStyle: {
    backgroundColor: 'transparent',
    padding: '0',
    gap: '12px',
    borderRadius: '0',
    height: '44px',
    minHeight: '44px'
  },

  // Tooltip styles
  tooltipStyle: {
    backgroundColor: 'rgba(0, 0, 0, 0.9)',
    color: 'white',
    fontSize: '12px',
    fontWeight: 500,
    padding: '6px 10px',
    borderRadius: '4px',
    showDelay: 500,
    hideDelay: 0
  },

  // Menu styles
  playbackSpeedMenuStyle: {
    backgroundColor: 'rgba(0, 0, 0, 0.9)',
    backdropFilter: 'blur(10px) saturate(180%)',
    borderColor: 'rgba(255, 255, 255, 0.1)',
    borderRadius: '8px',
    padding: '8px',
    fontSize: '14px',
    color: 'white',
    textShadow: 'rgba(0, 0, 0, 0.5) 0px 0px 2px'
  },

  qualityMenuStyle: {
    backgroundColor: 'rgba(0, 0, 0, 0.9)',
    backdropFilter: 'blur(10px) saturate(180%)',
    borderColor: 'rgba(255, 255, 255, 0.1)',
    borderRadius: '8px',
    padding: '8px',
    fontSize: '14px',
    color: 'white',
    textShadow: 'rgba(0, 0, 0, 0.5) 0px 0px 2px'
  },

  shareMenuStyle: {
    backgroundColor: 'rgba(0, 0, 0, 0.9)',
    backdropFilter: 'blur(10px) saturate(180%)',
    borderColor: 'rgba(255, 255, 255, 0.1)',
    borderRadius: '8px',
    padding: '8px',
    fontSize: '14px',
    color: 'white',
    textShadow: 'rgba(0, 0, 0, 0.5) 0px 0px 2px'
  },

  // Custom CSS variables (for advanced customization)
  customCSSVariables: {
    'custom-color': '#ff0000',
    'custom-size': '20px'
  }
};

const App = () => (
  <VideoPlayer
    src="/videos/sample.mp4"
    controlOptions={controlOptions}
  />
);

Control Options Interface

interface ControlOptions {
  // Visibility toggles
  showPlayButton?: boolean;
  showVolumeControl?: boolean;
  showTimeDisplay?: boolean;
  showSeekBar?: boolean;
  showPlaybackSpeed?: boolean;
  showQualitySelector?: boolean;
  showCaptionsButton?: boolean;
  showFullscreenButton?: boolean;
  showPictureInPictureButton?: boolean;
  showTheaterModeButton?: boolean;
  showSocialShare?: boolean;
  showChapterMarkers?: boolean;

  // Button styles
  playButtonStyle?: ControlButtonStyle;
  volumeButtonStyle?: ControlButtonStyle;
  controlButtonStyle?: ControlButtonStyle;
  rightControlsButtonStyle?: ControlButtonStyle;

  // Menu styles
  playbackSpeedMenuStyle?: ControlMenuStyle;
  qualityMenuStyle?: ControlMenuStyle;
  shareMenuStyle?: ControlMenuStyle;

  // Seek bar styles
  seekBarStyle?: {
    height?: string;
    hoverHeight?: string;
    backgroundColor?: string;
    playedColor?: string;
    bufferedColor?: string;
    thumbColor?: string;
    thumbSize?: string;
    hoverThumbSize?: string;
    borderRadius?: string;
  };

  // Volume slider styles
  volumeSliderStyle?: {
    width?: string;
    height?: string;
    backgroundColor?: string;
    fillColor?: string;
    thumbColor?: string;
    thumbSize?: string;
    borderRadius?: string;
  };

  // Time display styles
  timeDisplayStyle?: {
    fontSize?: string;
    fontWeight?: string | number;
    color?: string;
    backgroundColor?: string;
    backdropFilter?: string;
    borderColor?: string;
    borderRadius?: string;
    padding?: string;
    textShadow?: string;
  };

  // Controls bar styles
  controlsBarStyle?: {
    backgroundColor?: string;
    padding?: string;
    gap?: string;
    borderRadius?: string;
    minHeight?: string;
    height?: string;
  };

  // Tooltip styles
  tooltipStyle?: {
    backgroundColor?: string;
    color?: string;
    fontSize?: string;
    fontWeight?: string | number;
    padding?: string;
    borderRadius?: string;
    showDelay?: number;
    hideDelay?: number;
  };

  // Custom CSS variables (for advanced customization)
  customCSSVariables?: Record<string, string>;
}

interface ControlButtonStyle {
  backgroundColor?: string;
  hoverBackgroundColor?: string;
  activeBackgroundColor?: string;
  color?: string;
  borderColor?: string;
  borderRadius?: string;
  fontSize?: string;
  fontWeight?: string | number;
  padding?: string;
  width?: string;
  height?: string;
  minWidth?: string;
  minHeight?: string;
}

interface ControlMenuStyle {
  backgroundColor?: string;
  backdropFilter?: string;
  borderColor?: string;
  borderRadius?: string;
  padding?: string;
  fontSize?: string;
  fontWeight?: string | number;
  color?: string;
  textShadow?: string;
}

Example: Minimal Player

Create a minimal player with only essential controls:

<VideoPlayer
  src="/videos/sample.mp4"
  controlOptions={{
    showPlayButton: true,
    showVolumeControl: true,
    showTimeDisplay: true,
    showSeekBar: true,
    showPlaybackSpeed: false,
    showQualitySelector: false,
    showCaptionsButton: false,
    showFullscreenButton: true,
    showPictureInPictureButton: false,
    showTheaterModeButton: false,
    showSocialShare: false,
    showChapterMarkers: false
  }}
/>

Example: Custom Styled Player

Customize the appearance to match your brand:

<VideoPlayer
  src="/videos/sample.mp4"
  controlOptions={{
    playButtonStyle: {
      backgroundColor: 'rgba(255, 0, 0, 0.8)',
      hoverBackgroundColor: 'rgba(255, 0, 0, 1)',
      borderRadius: '50%',
      width: '56px',
      height: '56px'
    },
    seekBarStyle: {
      height: '10px',
      hoverHeight: '16px',
      playedColor: '#ff0000',
      thumbColor: '#ff0000',
      thumbSize: '18px',
      hoverThumbSize: '24px'
    },
    timeDisplayStyle: {
      fontSize: '16px',
      fontWeight: 600,
      color: '#ffffff',
      backgroundColor: 'rgba(0, 0, 0, 0.7)',
      borderRadius: '8px',
      padding: '6px 12px'
    }
  }}
/>

CSS Variables

You can also customize the player using CSS variables directly:

.rvp-video-player {
  /* Play Button */
  --rvp-play-btn-bg: rgba(0, 0, 0, 0.5);
  --rvp-play-btn-hover-bg: rgba(0, 0, 0, 0.9);
  --rvp-play-btn-color: white;
  --rvp-play-btn-radius: 50%;
  --rvp-play-btn-width: 48px;
  --rvp-play-btn-height: 48px;

  /* Seek Bar */
  --rvp-seekbar-height: 8px;
  --rvp-seekbar-hover-height: 14px;
  --rvp-seekbar-played: #ff0000;
  --rvp-seekbar-thumb: #ff0000;
  --rvp-seekbar-thumb-size: 16px;
  --rvp-seekbar-thumb-hover-size: 22px;

  /* Volume Slider */
  --rvp-volume-slider-width: 120px;
  --rvp-volume-slider-fill: #ff0000;
  --rvp-volume-slider-thumb: white;

  /* Time Display */
  --rvp-time-font-size: 14px;
  --rvp-time-color: white;
  --rvp-time-bg: rgba(0, 0, 0, 0.5);

  /* Tooltip */
  --rvp-tooltip-bg: rgba(0, 0, 0, 0.9);
  --rvp-tooltip-color: white;
  --rvp-tooltip-font-size: 12px;
}

🧩 Project Structure

react-video-player/ ├── src/ │ ├── components/ # All modular player components │ ├── hooks/ # Custom video hook │ ├── types/ # Type definitions │ ├── styles/ # CSS styles │ └── index.ts # Entry point ├── demo/ # Vite + manual CSS demo project ├── dist/ # Compiled output ├── package.json ├── tsconfig.json └── README.md

📚 Additional Examples

Quality Selection

import { VideoPlayer, VideoQuality } from 'react-video-player';

const qualities: VideoQuality[] = [
  { label: '1080p', value: '1080p', src: '/videos/sample-1080p.mp4' },
  { label: '720p', value: '720p', src: '/videos/sample-720p.mp4' },
  { label: '480p', value: '480p', src: '/videos/sample-480p.mp4' },
  { label: '360p', value: '360p', src: '/videos/sample-360p.mp4' }
];

const App = () => (
  <VideoPlayer
    src="/videos/sample.mp4"
    qualities={qualities}
    onQualityChange={(quality) => console.log('Quality changed to:', quality)}
  />
);

Chapters Support

import { VideoPlayer, Chapter } from 'react-video-player';

const chapters: Chapter[] = [
  { title: 'Introduction', startTime: 0, endTime: 30 },
  { title: 'Main Content', startTime: 30, endTime: 120 },
  { title: 'Conclusion', startTime: 120, endTime: 150 }
];

const App = () => (
  <VideoPlayer
    src="/videos/sample.mp4"
    chapters={chapters}
    onChapterChange={(chapter) => console.log('Chapter:', chapter.title)}
  />
);

Playlist Support

import { VideoPlayer, PlaylistItem } from 'react-video-player';

const playlist: PlaylistItem[] = [
  { src: '/videos/video1.mp4', title: 'Video 1', poster: '/posters/video1.jpg' },
  { src: '/videos/video2.mp4', title: 'Video 2', poster: '/posters/video2.jpg' },
  { src: '/videos/video3.mp4', title: 'Video 3', poster: '/posters/video3.jpg' }
];

const App = () => (
  <VideoPlayer
    src={playlist}
    onPlaylistItemChange={(index, item) => {
      console.log('Playing:', item.title, 'at index:', index);
    }}
  />
);

❌ Not Using

This package does NOT depend on:

• react-player
• video.js
• hls.js
• External UI frameworks
• Redux or global state

It’s written with vanilla React, DOM APIs, and TypeScript — fully maintainable and modular.

🤝 Contributing

We welcome feature suggestions, bug reports, and contributions!

• 📁 Clone the repo
• 💻 Create a feature branch
• ✅ Submit a PR

📄 License

MIT License
© 2025 – Arun

Made with ❤️ and TypeScript by Arun YT

🌟 Feedback Welcome

If you like this project, please consider giving it a star ⭐ and leaving feedback through GitHub Issues.
Your support helps keep this project actively maintained and improved.

📢 Discoverability Boost

To help more developers find and benefit from this project, it’s being submitted to:

• awesome-react-components
• madewithreactjs.com
• bestofjs.org