Quick Start

Now that you've installed the package and its peer dependencies, it's time to create your first working video player. This guide walks you through the essential steps to get a functional player running in your React application, from importing the component to configuring the required props.

Your First Video Player

The video player requires two essential elements to function: a video source and a set of icons for the player controls. Let's start with the absolute minimum configuration needed to render a player, then gradually add more features to enhance the experience.

Minimal Working Example

Here's the simplest possible implementation of the video player. This example demonstrates the bare minimum required props to get a player rendering on your page:

import { CustomVideoPlayer } from "@ntxmjs/react-custom-video-player";
import {
  PlayIcon,
  PauseIcon,
  VolumeIcon,
  VolumeMuteIcon,
  FullscreenIcon,
  ExitFullscreenIcon,
  PipIcon,
  SettingsIcon,
  SpeedIcon,
  CCIcon,
  BackIcon,
  CheckIcon,
  HDChipIcon,
  SleepTimerIcon
} from "./icons"; // Import your icon components

function App() {
  const playerIcons = {
    play: <PlayIcon size={26} />,
    pause: <PauseIcon size={26} />,
    volume: <VolumeIcon size={26} />,
    volumeMute: <VolumeMuteIcon size={26} />,
    fullscreen: <FullscreenIcon size={26} />,
    exitFullscreen: <ExitFullscreenIcon size={26} />,
    pip: <PipIcon size={26} />,
    settings: <SettingsIcon size={26} />,
    speed: <SpeedIcon size={26} />,
    cc: <CCIcon size={26} />,
    back: <BackIcon size={26} />,
    check: <CheckIcon size={26} />,
    hdChip: <HDChipIcon size={26} />,
    sleepTimer: <SleepTimerIcon size={26} />,
  };

  return (
    <div style={{ width: "800px", height: "450px", margin: "0 auto" }}>
      <CustomVideoPlayer
        src="https://example.com/your-video.mp4"
        poster="https://example.com/poster-image.jpg"
        icons={playerIcons}
      />
    </div>
  );
}

export default App;

This example creates a functional video player with all the essential controls. The player will render inside a container with defined dimensions, displaying your video with a poster image before playback begins.

What's Happening Here? The CustomVideoPlayer component receives three required props: src specifies the video file URL, poster provides a preview image shown before the video plays, and icons supplies React components for all the player controls. The icons configuration ensures every button in the player has a visual representation.

Understanding Required Props

Before diving into more advanced configurations, let's understand what each required prop does and why it's necessary.

Video Source

The src prop accepts a URL pointing to your video file. The player intelligently handles multiple video formats:

HLS Streams: URLs ending in .m3u8 are treated as HLS streams, enabling adaptive bitrate streaming. This format is ideal for delivering video at multiple quality levels, allowing the player to automatically adjust based on the viewer's network conditions.

src = "https://example.com/video/master.m3u8";

Standard Video Files: Direct links to MP4, WebM, or OGG files work as standard video sources. These formats are natively supported by browsers and don't require HLS.js for playback.

src = "https://example.com/video.mp4";

The player automatically detects the video type based on the file extension. You can also explicitly set the type using the type prop if needed, though the automatic detection works reliably in most cases.

Poster Image

The poster prop specifies an image URL that displays before the video begins playing. This image serves multiple purposes: it provides visual context about the video content, improves perceived loading performance by showing something immediately, and maintains a professional appearance while the video loads.

poster = "https://example.com/poster.jpg";

Choose a high-quality image that represents the video content well. The poster image should ideally match the video's aspect ratio to avoid any awkward stretching or cropping.

Icons Configuration

The icons prop is an object containing React components for every control in the player. Each property in this object corresponds to a specific button or visual element. Here's what each icon represents:

• play / pause: Main playback control buttons
• volume / volumeMute: Audio control icons that toggle between muted and unmuted states
• fullscreen / exitFullscreen: Icons for entering and exiting fullscreen mode
• pip: Picture-in-Picture mode toggle icon
• settings: Opens the settings panel for quality, speed, and subtitle controls
• speed: Represents playback speed options in the settings menu
• cc: Closed captions/subtitles toggle icon
• back: Navigation icon used in nested settings menus
• check: Indicator for selected options in menus
• hdChip: Badge showing high-definition quality indicator
• sleepTimer: Icon for the sleep timer feature

All fifteen icons must be provided for the player to function correctly. Missing any icon will result in a runtime error.

Adding Video Container Styles

While the minimal example works, you'll often want more control over how the player fits within your layout. The videoContainerStyles prop allows you to customize the dimensions and styling of both the player container and the video element itself.

import { CustomVideoPlayer } from "@ntxmjs/react-custom-video-player";

function App() {
  const playerIcons = {
    // ... icon configuration from previous example
  };

  // Default styles for the video container and video element
  const videoContainerStyles = {
    parent: {
      width: "100%",
      height: "-webkit-fill-available",
    },
    video: {
      width: "100%",
      height: "-webkit-fill-available",
    },
  };

  return (
    <div style={{ width: "100vw", height: "100vh" }}>
      <CustomVideoPlayer
        src="https://example.com/video.m3u8"
        poster="https://example.com/poster.jpg"
        icons={playerIcons}
        videoContainerStyles={videoContainerStyles}
      />
    </div>
  );
}

The videoContainerStyles object has two properties: parent controls the outer container that wraps the entire player, and video styles the actual video element. This separation gives you precise control over layout behavior, allowing the container to define overall dimensions while the video element handles how the content fills that space.

Common Use Cases: Setting objectFit: "contain" ensures the entire video is visible without cropping, ideal for videos with important edge content. Using objectFit: "cover" fills the container completely, potentially cropping the video but eliminating letterboxing. Responsive designs benefit from percentage-based widths combined with maximum dimensions.

Complete Working Example

Let's put everything together into a production-ready example that demonstrates best practices and includes additional useful configurations:

import { CustomVideoPlayer } from "@ntxmjs/react-custom-video-player";
import {
  Play,
  Pause,
  Volume2,
  VolumeX,
  Maximize,
  Minimize,
  PictureInPicture,
  Settings,
  Gauge,
  Subtitles,
  ChevronLeft,
  Check,
  Badge,
  Clock,
} from "lucide-react";

function VideoPlayer() {
  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} />,
  };

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

  return (
    <div
      style={{
        width: "min(90vw, 1200px)",
        height: "min(50vh, 675px)",
        margin: "0 auto",
        padding: "20px",
      }}
    >
      <CustomVideoPlayer
        src="https://nitiksh.github.io/test-data/videos/streaming/sipderman-brand-new-day/SPIDER_MAN_BRAND_NEW_DAY_master.m3u8"
        poster="https://ik.imagekit.io/nitiksh/spider-man-brand-new-day.webp"
        icons={icons}
        videoContainerStyles={containerStyles}
        enablePreviewOnHover={true}
      />
    </div>
  );
}

export default VideoPlayer;

This example demonstrates a well-structured implementation. It imports icons from the Lucide React library, configures all required icons with consistent sizing, applies container styles for a polished appearance with rounded corners, uses responsive dimensions that adapt to viewport size, and enables the preview-on-hover feature for enhanced user experience.

Why This Approach Works: Extracting the icon configuration into a separate object keeps your component clean and maintainable. The container styling creates a professional appearance with proper overflow handling. Responsive dimensions using min() CSS function ensure the player looks great on all screen sizes without requiring media queries.

Testing Your Implementation

After implementing the video player, verify that everything works correctly:

Visual Inspection: The poster image should display immediately when the component mounts. All control buttons should be visible at the bottom of the player. The player should fit properly within its container without overflow issues.

Basic Functionality: Click the play button to start playback. The video should begin playing, and the play icon should switch to a pause icon. Test the volume controls by clicking the volume icon and adjusting the slider. Enter fullscreen mode to confirm the player expands correctly.

HLS Streaming: If using an HLS source, open your browser's developer console. You should see the player loading different quality variants. The quality badge should appear if multiple qualities are available. Network throttling should trigger automatic quality switching.

Next Steps

With your first video player successfully running, you're ready to explore more advanced features:

Configuration: Learn about all available props in the Props documentation to customize player behavior, timing, and appearance settings.

Icons Customization: Discover how to use different icon libraries or create custom icons in the Icons Configuration guide.

Subtitles: Add multi-language captions to your videos with the Captions Configuration documentation.

Theming: Customize the player's visual appearance to match your brand with the Theming guide.

Advanced Features: Explore keyboard shortcuts, preview thumbnails, and other power-user features in the Advanced Features section.

The quick start covered the essentials to get you up and running. The player offers extensive customization options that you can explore as your needs grow. Start with this basic implementation and gradually add features as you become more comfortable with the component.