Props

The CustomVideoPlayer component accepts a variety of props that control its behavior, appearance, and functionality. Understanding these props is essential for customizing the player to meet your specific requirements. This comprehensive guide covers every available prop, explaining what it does, when to use it, and how it affects the player's behavior.

Required Props

These props must be provided for the player to function correctly. Omitting any required prop will result in a runtime error or non-functional player.

src

Type: string

Required: Yes

The src prop specifies the URL of the video file you want to play. This is the most fundamental prop, as it tells the player what content to load and display.

The player intelligently handles different video formats based on the URL structure. For HLS streams, provide a URL ending in .m3u8. This format enables adaptive bitrate streaming, where the player automatically switches between quality levels based on network conditions and device capabilities.

// HLS stream for adaptive quality
<CustomVideoPlayer
  src="https://example.com/video/master.m3u8"
  poster="..."
  icons={icons}
/>

For standard video files like MP4, WebM, or OGG, provide a direct URL to the video file. These formats play natively in browsers without requiring HLS.js.

// Standard MP4 video
<CustomVideoPlayer
  src="https://example.com/videos/sample.mp4"
  poster="..."
  icons={icons}
/>

How It Works: When you provide an HLS URL, the player uses HLS.js to parse the manifest file, detect available quality levels, and manage the streaming process. For standard formats, the browser's native video capabilities handle playback. The player automatically determines which approach to use based on the file extension.

poster

Type: string

Required: Yes

The poster prop specifies the URL of an image that displays before the video begins playing. This image serves as a preview thumbnail, giving viewers context about the video content while the player loads or before they press play.

<CustomVideoPlayer
  src="https://example.com/video.m3u8"
  poster="https://example.com/posters/video-preview.jpg"
  icons={icons}
/>

Best Practices: Choose a poster image that accurately represents the video content. The image should ideally match your video's aspect ratio to prevent distortion or letterboxing. High-resolution images work best, but ensure the file size is optimized for quick loading. A poster image between 100KB and 500KB typically provides good quality without sacrificing performance.

The poster image disappears once playback begins and reappears if the user returns to the beginning or if playback fails. This creates a polished, professional appearance and ensures users always see meaningful content rather than a black screen.

icons

Type: IconSet

Required: Yes

The icons prop is an object containing React components for every control button and visual indicator in the player. This prop gives you complete control over the player's visual appearance by allowing you to use any icon library or custom SVG components.

import {
  Play,
  Pause,
  Volume2,
  VolumeX,
  Maximize,
  Minimize,
} from "lucide-react";

const icons = {
  play: <Play size={26} />,
  pause: <Pause size={26} />,
  volume: <Volume2 size={26} />,
  volumeMute: <VolumeX size={26} />,
  fullscreen: <Maximize size={26} />,
  exitFullscreen: <Minimize size={26} />,
  pip: <PictureInPicture size={26} />,
  settings: <Settings size={26} />,
  speed: <Gauge size={26} />,
  cc: <Subtitles size={26} />,
  back: <ChevronLeft size={26} />,
  check: <Check size={26} />,
  hdChip: <Badge size={26} />,
  sleepTimer: <Clock size={26} />,
};

<CustomVideoPlayer src="..." poster="..." icons={icons} />;

All fifteen icon properties must be present in the object. Each property should contain a valid React element. The player will throw an error if any icon is missing or invalid.

Icon Customization: You can use any icon library including Lucide React, React Icons, Heroicons, Font Awesome, or custom SVG components. The recommended size is 26 pixels for consistency with the player's design, but you can adjust this to match your design system. Icons automatically inherit the player theme's color scheme, ensuring visual consistency.

Optional Props

These props provide additional configuration options and features. The player works perfectly with default values, but you can customize these to enhance functionality or match your specific requirements.

captions

Type: CaptionTrack[]

Default: []

The captions prop accepts an array of subtitle track objects, enabling multi-language caption support. Each caption track specifies a subtitle file in WebVTT format along with metadata about the language and display label.

const captions = [
  {
    src: "https://example.com/subtitles/english.vtt",
    srclang: "en",
    label: "English",
    default: true,
  },
  {
    src: "https://example.com/subtitles/spanish.vtt",
    srclang: "es",
    label: "Español",
    default: false,
  },
  {
    src: "https://example.com/subtitles/french.vtt",
    srclang: "fr",
    label: "Français",
    default: false,
  },
];

<CustomVideoPlayer src="..." poster="..." icons={icons} captions={captions} />;

Caption Track Properties: Each caption object requires four properties. The src is the URL to the WebVTT subtitle file. The srclang is a two-letter language code such as "en", "es", or "fr". The label is the display name shown to users in the captions menu. The default boolean indicates which track should be active when the player loads.

Only one caption track should have default: true. If multiple tracks are marked as default, the player uses the first one in the array. If no track is marked as default, captions remain off until the user manually enables them.

The player renders captions using a custom subtitle engine rather than native browser controls, allowing for consistent styling across all browsers and devices. Users can cycle through available captions using the keyboard shortcut C or by selecting from the settings menu.

startTime

Type: number

Default: 0

The startTime prop sets the initial playback position in seconds. When the video loads, playback begins at this timestamp rather than at the beginning of the video.

// Start video at 1 minute 30 seconds
<CustomVideoPlayer src="..." poster="..." icons={icons} startTime={90} />

Use Cases: This prop is particularly useful for resuming playback from a saved position, creating video previews that start at specific moments, implementing chapter-based navigation, or highlighting specific scenes in longer content. For example, if you're building a course platform, you might use startTime to resume videos where users left off in their previous session.

The player seeks to the specified time once the video metadata loads. If the specified time exceeds the video duration, the player defaults to the beginning. Seeking happens automatically and smoothly without requiring user interaction.

className

Type: string

Default: undefined

The className prop allows you to apply custom CSS classes to the player's root container element. This enables integration with your application's styling system and provides flexibility for custom layouts.

<CustomVideoPlayer
  src="..."
  poster="..."
  icons={icons}
  className="my-custom-video-player shadow-lg rounded-xl"
/>

Use this prop to add utility classes from CSS frameworks like Tailwind, apply custom CSS classes from your stylesheets, or add classes for animation and transition effects. The classes apply to the outermost container and don't affect the internal player structure, preserving the player's functionality and built-in styling.

theme

Type: "light" | "dark" | Theme

Default: "dark"

The theme prop controls the visual appearance of the player. You can use one of the built-in themes or provide a custom theme object for complete visual customization.

Built-in Themes:

// Dark theme (default)
<CustomVideoPlayer theme="dark" src="..." poster="..." icons={icons} />

// Light theme
<CustomVideoPlayer theme="light" src="..." poster="..." icons={icons} />

Custom Theme:

const customTheme = {
  colors: {
    background: "linear-gradient(135deg, #1a1a2e, #16213e)",
    text: "#eaeaea",
    accent: "#0f4c75",
    accentHover: "#3282b8",
    // ... additional color properties
  },
  fonts: {
    primary: "Inter, sans-serif",
    size: {
      small: "12px",
      medium: "14px",
      large: "16px",
    },
  },
  borderRadius: {
    small: "4px",
    medium: "8px",
    large: "12px",
  },
  spacing: {
    small: "8px",
    medium: "12px",
    large: "16px",
  },
};

<CustomVideoPlayer theme={customTheme} src="..." poster="..." icons={icons} />;

The built-in themes provide professional, accessible color schemes that work well in most applications. The dark theme uses darker backgrounds with light text, ideal for video-focused interfaces and reducing eye strain in low-light environments. The light theme uses lighter backgrounds with dark text, suitable for bright environments and modern web applications.

Custom themes give you granular control over every visual aspect. You can override individual properties while keeping others at their default values. The theme system ensures all colors remain consistent and accessible across the entire player interface.

controlSize

Type: number

Default: 40

The controlSize prop sets the size of control buttons in pixels. This affects all interactive elements including play/pause, volume, fullscreen, and settings buttons.

// Larger controls for better touch targets on mobile
<CustomVideoPlayer
  src="..."
  poster="..."
  icons={icons}
  controlSize={48}
/>

// Smaller controls for compact layouts
<CustomVideoPlayer
  src="..."
  poster="..."
  icons={icons}
  controlSize={32}
/>

The default size of 40 pixels provides good usability on both desktop and mobile devices. Larger sizes improve touch targets for mobile users but consume more screen space. Smaller sizes create a more compact interface but may reduce accessibility. Consider your target devices and user needs when adjusting this value.

The player automatically scales icon sizes and spacing to match the control size, maintaining visual harmony across all interface elements. This ensures the player looks polished regardless of the control size you choose.

type

Type: "hls" | "mp4" | "auto"

Default: "auto"

The type prop explicitly specifies the video format type, overriding the player's automatic detection. In most cases, the automatic detection works perfectly, but you can force a specific type when needed.

// Force HLS handling even without .m3u8 extension
<CustomVideoPlayer
  src="https://example.com/video/stream"
  poster="..."
  icons={icons}
  type="hls"
/>

// Force standard video handling
<CustomVideoPlayer
  src="https://example.com/video"
  poster="..."
  icons={icons}
  type="mp4"
/>

When to Use: The auto setting works for 99% of use cases, automatically detecting the format from the URL extension. Use type="hls" when your HLS URLs don't end in .m3u8 or when dealing with custom streaming endpoints. Use type="mp4" to force native video handling even if the URL might suggest HLS streaming.

Setting an incorrect type can cause playback failures. If you're unsure, leave this prop at its default auto value and let the player determine the appropriate handling method.

enablePreviewOnHover

Type: boolean

Default: true

The enablePreviewOnHover prop controls whether the player displays video preview thumbnails when hovering over the progress bar. When enabled, users see a small preview of the video at the hovered timestamp, making navigation more intuitive and precise.

// Enable preview (default)
<CustomVideoPlayer
  src="..."
  poster="..."
  icons={icons}
  enablePreviewOnHover={true}
/>

// Disable preview
<CustomVideoPlayer
  src="..."
  poster="..."
  icons={icons}
  enablePreviewOnHover={false}
/>

How It Works: For HLS streams, the player uses the lowest quality variant to generate previews efficiently, minimizing bandwidth usage. For standard video files, the player attempts to generate previews from the main video source. This feature enhances the user experience significantly by allowing viewers to see exactly where they're navigating before clicking.

videoContainerStyles

Type: VideoContainerStyles

Default: undefined

The videoContainerStyles prop provides fine-grained control over the styling of the player's container and video element. This object accepts CSS-in-JS style properties for both the parent container and the video element itself.

const containerStyles = {
  parent: {
    width: "100%",
    height: "-webkit-fill-available",
  },
  video: {
    width: "100%",
    height: "-webkit-fill-available",
  },
};

<CustomVideoPlayer
  src="..."
  poster="..."
  icons={icons}
  videoContainerStyles={containerStyles}
/>;

Parent Styles: The parent object styles the outer container wrapping the entire player. Use this to control dimensions, positioning, borders, shadows, and layout behavior. Common properties include width, height, maxWidth, margin, padding, borderRadius, and overflow.

Video Styles: The video object styles the actual HTML video element. The most important property here is objectFit, which controls how the video content fills its container. Use contain to ensure the entire video is visible without cropping, or cover to fill the container completely, potentially cropping the video edges.

This prop is particularly useful for creating responsive layouts, implementing custom aspect ratios, and ensuring the player fits perfectly within your application's design. The styles merge with the player's default styles, so you only need to specify properties you want to override.

Props Summary Table

Here's a quick reference table showing all available props, their types, and default values:

Common Configuration Patterns

Understanding individual props is important, but seeing how they work together in real-world scenarios helps you implement the player effectively.

Basic Video Player:

<CustomVideoPlayer
  src="https://example.com/video.mp4"
  poster="https://example.com/poster.jpg"
  icons={icons}
/>

This minimal configuration creates a functional player with default settings—perfect for simple video playback needs.

Video Player with Captions:

<CustomVideoPlayer
  src="https://example.com/video.m3u8"
  poster="https://example.com/poster.jpg"
  icons={icons}
  captions={[
    { src: "subtitles-en.vtt", srclang: "en", label: "English", default: true },
    {
      src: "subtitles-es.vtt",
      srclang: "es",
      label: "Spanish",
      default: false,
    },
  ]}
/>

Adding captions makes your content accessible to a wider audience and improves the viewing experience for users in sound-sensitive environments.

Resume Playback Configuration:

<CustomVideoPlayer
  src="https://example.com/video.mp4"
  poster="https://example.com/poster.jpg"
  icons={icons}
  startTime={savedPosition}
  enablePreviewOnHover={true}
/>

This pattern works well for course platforms, video series, or any application where users might want to resume watching from where they left off.

Custom Branded Player:

<CustomVideoPlayer
  src="https://example.com/video.m3u8"
  poster="https://example.com/poster.jpg"
  icons={customIcons}
  theme={brandTheme}
  className="branded-video-player"
  controlSize={44}
/>

Complete customization allows the player to match your brand identity perfectly, creating a cohesive user experience across your application.

Next Steps

Now that you understand all available props, you can explore more specific configuration topics:

Icons Configuration: Learn detailed strategies for customizing player icons with different libraries and creating custom icon components.

Captions Configuration: Dive deeper into subtitle configuration, including VTT file creation, multi-language support, and custom caption styling.

Theming: Explore the complete theming system to create custom visual designs that match your brand perfectly.

Understanding these props gives you the foundation needed to implement the video player effectively in any React application. Experiment with different combinations to find the configuration that works best for your specific use case.