🎬 InteractiveVideoPlayer

A modern, customizable, React-based HTML5 video player with timed overlays, fullscreen support, and custom controls — all built without bulky libraries.

⚡ Lightweight · 🚀 Performant · 🎨 Fully Styleable · 🧠 Built for Interactive Content

✨ Features

• ✅ Native HTML5 <video> — no external video libraries
• 🧩 Time-based overlays (auto-pause supported)
• 🎮 Custom controls (play, pause, mute, fullscreen, seek)
• 🖼️ Poster image support
• ⛶ Fullscreen mode (desktop & iOS)
• 📱 Fully responsive
• 🎨 Easily styleable via props
• 💡 Designed for learning, onboarding, training, and media-rich storytelling

📦 Installation

# Required for icons
npm install @phosphor-icons/react

# Install the video player component
npm install @kuldeep363/interactive-video-player

⚡ Quick Usage

import InteractiveVideoPlayer from "@kuldeep363/interactive-video-player";

const overlays = [
  {
    id: "intro",
    start: 5,
    end: 10,
    content: <div className="p-4 bg-white rounded">👋 Welcome!</div>,
    stopOnEntry: true,
  },
  {
    id: "cta",
    start: 15,
    end: 20,
    content: (
      <button
        className="px-4 py-2 bg-blue-600 text-white rounded"
        onClick={() => alert("CTA Clicked")}
      >
        Learn More
      </button>
    ),
  },
];

export default function App() {
  return (
    <InteractiveVideoPlayer
      videoSrc="/videos/sample.mp4"
      poster="/images/poster.jpg"
      overlays={overlays}
      width="100%"
      height="auto"
      containerClassName="max-w-4xl mx-auto mt-8"
      videoClassName="rounded-lg"
      overlayWrapperClassName="z-50"
      showSeekBar={true}
    />
  );
}

⚙️ Component Props

| Prop | Type | Default | Description | | ------------------------- | ----------- | ----------- | ---------------------------------- | | videoSrc | string | required | Video file source URL | | poster | string | undefined | Optional poster image | | overlays | Overlay[] | [] | Array of timed overlays | | width | string | "100%" | Player container width | | height | string | "auto" | Player container height | | containerClassName | string | "" | Custom class for outer container | | videoClassName | string | "" | Custom class for <video> element | | overlayWrapperClassName | string | "" | Custom class for overlay wrapper | | controlsClassName | string | "" | Custom class for controls wrapper | | showControls | boolean | true | Show or hide playback controls | | showSeekBar | boolean | true | Show or hide seek bar |

🧩 Overlay Config

Overlays appear at specific video times. Great for quizzes, CTAs, or interactive content.

Overlay Type

type Overlay = {
  id: string;
  content: React.ReactNode;
  start?: number;
  end?: number;
  offset?: number;
  relativeTo?: "start" | "end";
  duration?: number;
  stopOnEntry?: boolean;
  onClick?: (resume: () => void) => void;
};

| Prop | Type | Required | Description | | ------------- | ------------------------------ | -------- | ------------------------------------------------ | | id | string | ✅ Yes | Unique ID | | content | React.ReactNode | ✅ Yes | JSX/HTML to display | | start | number | ❌ No | Absolute start time in seconds | | end | number | ❌ No | Absolute end time in seconds | | offset | number | ❌ No | Relative time (requires relativeTo) | | relativeTo | "start" | "end" | ❌ No | Base for offset | | duration | number | ❌ No | Duration to display overlay (used with offset) | | stopOnEntry | boolean | ❌ No | Pause video when overlay appears | | onClick | (resume: () => void) => void | ❌ No | Resume playback via callback |

🧪 Overlay Example

const overlays = [
  {
    id: "quiz-1",
    offset: 5,
    duration: 5,
    relativeTo: "start",
    stopOnEntry: true,
    content: (
      <div style={{ background: "#fff", padding: "1rem", borderRadius: "8px" }}>
        <h4>Quick Question</h4>
        <p>What is the capital of France?</p>
        <button onClick={() => alert("Correct!")}>Paris</button>
      </div>
    ),
  },
  {
    id: "customPause",
    offset: 15,
    relativeTo: "start",
    stopOnEntry: true,
    content: <div className="overlay">Processing...</div>,
    onClick: async (resume) => {
      await new Promise((res) => setTimeout(res, 1500));
      resume();
    },
  },
];

🧰 Control Features

| Feature | Description | | ------------- | ----------------------- | | ▶️ Play/Pause | Toggle playback | | 🔇 Mute | Toggle audio | | 📈 Seek Bar | Scrub through video | | ⛶ Fullscreen | Desktop & iOS support | | 📱 Mobile | Fully responsive layout |

🎨 Styling & Customization

Style everything via class props:

| Prop Name | Affects | | ------------------------- | ------------------ | | containerClassName | Outer player shell | | videoClassName | <video> element | | overlayWrapperClassName | Overlay container | | controlsClassName | Bottom control bar |

Also supports Tailwind or custom CSS. Include your own .css if needed.

📁 Suggested Project Structure

src/
├── components/
│   └── InteractiveVideoPlayer.tsx
├── pages/
│   └── index.tsx
public/
├── videos/
│   └── demo.mp4
├── images/
│   └── poster.jpg

🛠 Roadmap

• [ ] Volume slider
• [ ] Keyboard shortcuts
• [ ] Playback speed control
• [ ] Subtitles support
• [ ] Accessibility (ARIA)
• [ ] Preview thumbnails on seek
• [ ] Buffer/load indicators

📜 License

MIT — Free for personal or commercial use.

🤝 Contributing

1. Fork this repo
2. Create a branch: git checkout -b feature/your-feature
3. Make changes and commit: git commit -m "Add feature"
4. Push changes: git push origin feature/your-feature
5. Open a pull request

👤 Author

Kuldeep Rawat 🔗 kuldeeprawat.com

💬 Questions? Feedback?

• Open a GitHub issue
• Submit a PR
• Share ideas — Let’s build the best interactive player together!