React YouTube Player with Seekbar

A fully-typed React component for embedding YouTube videos in Next.js applications with advanced playback controls and a customizable seekbar.

📋 Table of Contents

• Features
• Installation
• Quick Start
• API Reference
  • YoutubePlayerProvider
  • YoutubePlayerWithSeekbar
  • useYoutubePlayer Hook
• Advanced Usage
• TypeScript Support
• Examples
• Contributing
• License

✨ Features

• 🎯 Full TypeScript Support: Built with TypeScript for excellent type safety and IntelliSense
• 🎮 Advanced Controls: Play, pause, seek, and reset functionality
• ⚡ Performance Optimized: Minimal re-renders and efficient state management
• 🎨 Customizable: Easily style and extend components
• 📱 Responsive: Works across all device sizes
• 🔄 State Management: Built-in context for managing player state
• 🎬 YouTube API Integration: Seamless integration with YouTube's IFrame API

🚀 Installation

# Using npm
npm install @nishansanjuka/react-yt-framer

# Using yarn
yarn add @nishansanjuka/react-yt-framer

# Using pnpm
pnpm add @nishansanjuka/react-yt-framer

🎯 Quick Start

import {
  YoutubePlayerProvider,
  YoutubePlayerWithSeekbar,
} from "@nishansanjuka/react-yt-framer";

function App() {
  return (
    <YoutubePlayerProvider>
      <YoutubePlayerWithSeekbar
        videoId="dQw4w9WgXcQ"
        className="aspect-video w-full"
      />
    </YoutubePlayerProvider>
  );
}

📖 API Reference

YoutubePlayer Provider

The provider component that manages the YouTube player state and context.

import { YoutubePlayerProvider } from "@nishansanjuka/react-yt-framer";

function App() {
  return <YoutubePlayerProvider>{/* Your components */}</YoutubePlayerProvider>;
}

YoutubePlayer With Seekbar

The main component that renders the YouTube player.

interface YoutubePlayerWithSeekbarProps {
  videoId: string;
  className?: string;
}

Props

| Prop | Type | Description | | --------- | ------- | -------------------- | | videoId | string | YouTube video ID | | className | string? | Optional CSS classes |

useYoutubePlayer Hook

A custom hook for accessing player controls and state.

const {
  duration,
  currentTime,
  isPlaying,
  isAPIReady,
  play,
  pause,
  seek,
  reset,
  setIsPlaying,
} = useYoutubePlayer();

Return Values

| Value | Type | Description | | ------------ | -------------------------- | ------------------------------------ | | duration | number | Total video duration in seconds | | currentTime | number | Current playback position in seconds | | isPlaying | boolean | Whether video is currently playing | | isAPIReady | boolean | Whether YouTube API is loaded | | play | () => void | Function to play video | | pause | () => void | Function to pause video | | seek | (time: number) => void | Function to seek to specific time | | reset | () => void | Function to reset video to start | | setIsPlaying | (playing: boolean) => void | Function to set playing state |

🎨 Advanced Usage

Custom Controls Example

import { useYoutubePlayer } from "@nishansanjuka/react-yt-framer";

function CustomControls() {
  const { play, pause, isPlaying, currentTime, duration, seek } =
    useYoutubePlayer();

  const handleSeek = (e: React.ChangeEvent<HTMLInputElement>) => {
    seek(Number(e.target.value));
  };

  return (
    <div className="flex gap-2 items-center">
      <button onClick={isPlaying ? pause : play}>
        {isPlaying ? "Pause" : "Play"}
      </button>
      <input
        type="range"
        min={0}
        max={duration}
        value={currentTime}
        onChange={handleSeek}
      />
      <span>
        {Math.floor(currentTime)} / {Math.floor(duration)}s
      </span>
    </div>
  );
}

Multiple Players

function VideoGallery() {
  return (
    <div className="grid grid-cols-2 gap-4">
      <YoutubePlayerProvider>
        <YoutubePlayerWithSeekbar videoId="video1" />
      </YoutubePlayerProvider>
      <YoutubePlayerProvider>
        <YoutubePlayerWithSeekbar videoId="video2" />
      </YoutubePlayerProvider>
    </div>
  );
}

🔍 TypeScript Support

The package includes comprehensive TypeScript definitions. Here are some key types:

interface YouTubePlayer {
  playVideo(): void;
  pauseVideo(): void;
  seekTo(seconds: number, allowSeekAhead?: boolean): void;
  stopVideo(): void;
  getCurrentTime(): number;
  getDuration(): number;
  getPlayerState(): number;
}

interface YoutubePlayerContextType {
  duration: number;
  currentTime: number;
  isPlaying: boolean;
  isAPIReady: boolean;
  registerPlayer: (player: YouTubePlayer) => void;
  seek: (time: number) => void;
  play: () => void;
  pause: () => void;
  reset: () => void;
  setIsPlaying: (playing: boolean) => void;
}

💡 Examples

Basic Player

function BasicPlayer() {
  return (
    <YoutubePlayerProvider>
      <YoutubePlayerWithSeekbar
        videoId="dQw4w9WgXcQ"
        className="w-full aspect-video rounded-lg shadow-lg"
      />
    </YoutubePlayerProvider>
  );
}

Player with Custom Controls and Progress Bar

function CustomPlayer() {
  const { currentTime, duration, seek, isPlaying, play, pause } =
    useYoutubePlayer();

  const progress = (currentTime / duration) * 100;

  return (
    <div className="space-y-4">
      <YoutubePlayerWithSeekbar videoId="dQw4w9WgXcQ" />

      <div className="flex items-center gap-4">
        <button
          onClick={isPlaying ? pause : play}
          className="px-4 py-2 bg-blue-500 text-white rounded"
        >
          {isPlaying ? "Pause" : "Play"}
        </button>

        <div className="flex-1 bg-gray-200 h-2 rounded">
          <div
            className="bg-blue-500 h-full rounded"
            style={{ width: `${progress}%` }}
          />
        </div>

        <span className="text-sm">
          {Math.floor(currentTime)}s / {Math.floor(duration)}s
        </span>
      </div>
    </div>
  );
}

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🎯 Troubleshooting

Common Issues

1. YouTube API Not Loading

// Make sure you're using the Provider
<YoutubePlayerProvider>
  <YourComponent />
</YoutubePlayerProvider>

2. Type Errors

// Import types directly
import type { YoutubePlayerContextType } from "@nishansanjuka/react-yt-framer";

3. Player Not Mounting

// Ensure videoId is valid
<YoutubePlayerWithSeekbar videoId="valid-youtube-id" />

📦 Package Structure

@nishansanjuka/react-yt-framer/
├── dist/
│   ├── cjs/           # CommonJS bundle
│   ├── esm/           # ES Modules bundle
│   └── index.d.ts     # TypeScript declarations
├── src/
│   ├── components/    # React components
│   └── types/        # TypeScript types
└── package.json

🔄 Updates and Versioning

We follow Semantic Versioning. Here's a summary of what each number means:

• Major version when making incompatible API changes
• Minor version when adding functionality in a backwards compatible manner
• Patch version when making backwards compatible bug fixes

Check the CHANGELOG.md for detailed release notes.

Made with ❤️ by Nipuna Nishan