Docs
YouTube Video Player

YouTube Video Player

A modern YouTube video player component with expandable modal view, custom thumbnails, and smooth animations.

Installation

npx shadcn@latest add https://cult-ui.com/r/youtube-video-player.json

Usage

import { YouTubePlayer } from "@/components/ui/youtube-video-player"
export default function Example() {
  return (
    <YouTubePlayer
      videoId="dQw4w9WgXcQ"
      title="Never Gonna Give You Up - Rick Astley"
    />
  )
}

Props

PropTypeDefaultDescription
videoIdstring-YouTube video ID or full URL
titlestring-Video title displayed on thumbnail
defaultExpandedbooleanfalseStart in expanded modal view
customThumbnailstring-Custom thumbnail image URL
classNamestring-Additional CSS classes for container
containerClassNamestring-CSS classes for video container
expandedClassNamestring-CSS classes for expanded modal view
thumbnailClassNamestring-CSS classes for thumbnail container
thumbnailImageClassNamestring-CSS classes for thumbnail image
playButtonClassNamestring-CSS classes for play button
playIconClassNamestring-CSS classes for play icon
titleClassNamestring-CSS classes for video title
controlsClassNamestring-CSS classes for controls container
expandButtonClassNamestring-CSS classes for expand/minimize button
backdropClassNamestring-CSS classes for modal backdrop
playerClassNamestring-CSS classes for player container

Examples

Basic Player

<YouTubePlayer
  videoId="dQw4w9WgXcQ"
  title="Never Gonna Give You Up - Rick Astley"
/>

With Custom Thumbnail

<YouTubePlayer
  videoId="jNQXAC9IVRw"
  title="Me at the zoo - First YouTube Video"
  customThumbnail="https://images.unsplash.com/photo-1611162617474-5b21e879e113?w=800&h=450&fit=crop&crop=center"
/>

Default Expanded

<YouTubePlayer
  videoId="ScMzIvxBSi4"
  title="The Evolution of Dance"
  defaultExpanded={true}
/>

Custom Styling

<YouTubePlayer
  videoId="kJQP7kiw5Fk"
  title="Despacito - Luis Fonsi ft. Daddy Yankee"
  containerClassName="border-2 border-primary rounded-2xl shadow-2xl"
  thumbnailImageClassName="opacity-90 saturate-150"
  playButtonClassName="bg-primary/20 border-primary hover:bg-primary/30"
  playIconClassName="text-primary fill-primary"
  titleClassName="text-primary font-bold"
  controlsClassName="right-4 top-4"
  expandButtonClassName="bg-primary/20 hover:bg-primary/30 border-primary"
/>

Multiple Players Grid

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  <YouTubePlayer
    videoId="9bZkp7q19f0"
    title="PSY - GANGNAM STYLE"
    className="w-full"
  />
  <YouTubePlayer
    videoId="fJ9rUzIMcZQ"
    title="Queen – Bohemian Rhapsody"
    className="w-full"
  />
  <YouTubePlayer
    videoId="L_jWHffIx5E"
    title="Smash Mouth - All Star"
    className="w-full"
  />
</div>

URL Format Support

The component automatically handles different YouTube URL formats:

// Video ID
<YouTubePlayer videoId="dQw4w9WgXcQ" />
 
// Full YouTube URL
<YouTubePlayer videoId="https://www.youtube.com/watch?v=dQw4w9WgXcQ" />
 
// Short URL
<YouTubePlayer videoId="https://youtu.be/dQw4w9WgXcQ" />

Advanced Usage

With All Customization Options

import { YouTubePlayer } from "@/components/ui/youtube-video-player"
 
export default function AdvancedPlayer() {
  return (
    <div className="max-w-4xl mx-auto p-8">
      <YouTubePlayer
        videoId="dQw4w9WgXcQ"
        title="Custom Styled Player"
        customThumbnail="/custom-thumbnail.jpg"
        defaultExpanded={false}
        // Container styling
        className="mb-8"
        containerClassName="border-2 border-gradient rounded-xl overflow-hidden shadow-lg"
        expandedClassName="border-none shadow-2xl"
        // Thumbnail styling
        thumbnailClassName="bg-gradient-to-br from-blue-500/20 to-purple-500/20"
        thumbnailImageClassName="opacity-80 transition-opacity hover:opacity-100"
        // Play button styling
        playButtonClassName="bg-white/90 hover:bg-white border-2 border-blue-500 shadow-lg"
        playIconClassName="text-blue-500 fill-blue-500"
        // Title styling
        titleClassName="text-white font-bold text-lg drop-shadow-lg"
        // Controls styling
        controlsClassName="right-3 top-3"
        expandButtonClassName="bg-black/50 hover:bg-black/70 border border-white/20"
        // Modal styling
        backdropClassName="bg-black/60 backdrop-blur-md"
        playerClassName="bg-black rounded-lg"
      />
    </div>
  )
}

Component Architecture

The YouTube Player consists of two main sub-components:

YouTubePlayer (Main Component)

The primary component that handles the video player logic, state management, and rendering. It includes:

  • Thumbnail display with custom image support
  • Play button with customizable styling
  • Expandable modal functionality
  • URL parsing for different YouTube formats
  • Keyboard shortcuts (ESC to close modal)

YouTubePlayerControls

A separate component for the expand/minimize controls that can be used independently:

import { YouTubePlayerControls } from "@/components/ui/youtube-video-player"
 
;<YouTubePlayerControls
  videoId="unique-id"
  expanded={false}
  playing={false}
  isHovered={true}
  onToggleExpand={() => {}}
  controlsClassName="custom-controls"
  expandButtonClassName="custom-expand-btn"
/>

Features

Core Features

  • Expandable Modal: Full-screen modal view with smooth animations
  • Custom Thumbnails: Support for custom thumbnail images
  • URL Flexibility: Handles video IDs, full URLs, and short URLs
  • Responsive Design: Works seamlessly across all device sizes
  • Keyboard Navigation: ESC key closes expanded view

User Experience

  • Smooth Animations: Powered by Framer Motion for fluid transitions
  • Hover Effects: Interactive controls that appear on hover
  • Loading States: Graceful handling of video loading
  • Accessibility: ARIA labels and keyboard support

Customization

  • Extensive Styling: 12+ className props for complete customization
  • Flexible Layout: Works in grids, cards, and custom containers
  • Theme Integration: Follows your design system colors and spacing
  • Component Composition: Sub-components can be used independently

Accessibility

The YouTube Player includes comprehensive accessibility features:

  • ARIA Labels: Proper labeling for screen readers
  • Keyboard Navigation: Full keyboard support including ESC to close
  • Focus Management: Proper focus handling in modal states
  • Semantic HTML: Uses appropriate HTML elements and structure
  • High Contrast: Respects system preferences for reduced motion

Browser Support

  • Modern browsers with ES2018+ support
  • Requires JavaScript enabled for video playback
  • Falls back gracefully when YouTube embed is blocked
  • Mobile-first responsive design

Performance

  • Lazy Loading: Videos only load when play button is clicked
  • Optimized Animations: GPU-accelerated transforms with Framer Motion
  • Efficient Re-renders: Minimal state updates and memoization
  • Lightweight Bundle: Only includes necessary dependencies