Video player

ImageKit's video player is an advanced video player built on top of Video.js 8.20.0 delivering enhanced features for a seamless, interactive video experience. It's fully integrated with ImageKit's video delivery and transformation solution.

Key features

Video transformations: Apply ImageKit video transformations at the player level that will apply to all videos delivered in that player. Apply additional or override video transformations at the per-video level.
Adaptive bitrate streaming: Full support for HLS and MPEG-DASH including automatic generation of all required streaming representations and supporting files. Learn more about ABS here.
Subtitles and chapters: Easy addition of subtitles, captions, and chapter markers to organize and navigate your video content. See subtitles and captions and chapters.
Player enhancements: Floating player that appears when scrolled out of view, and seek thumbnails that show previews when hovering over the progress bar.
Custom branding: Add a clickable logo to brand your video player and link to your website.
Playlists and recommendations: Create playlists of multiple videos with a scrollable widget, or display recommended videos when a video ends. See playlist and recommendations.
Shoppable Video: Make your videos shoppable by displaying product images alongside your videos. This allows your users to visit your product detail pages and make a purchase. See shoppable videos.

Installation

Install the package using npm or yarn:

Copy

npm install @imagekit/video-player
# or
yarn add @imagekit/video-player

For JavaScript with CDN, add these links to your HTML:

Copy

<link rel="stylesheet" href="https://unpkg.com/@imagekit/video-player@latest/dist/styles.css" />
<script src="https://unpkg.com/@imagekit/video-player@latest/dist/index.js"></script>

Tip: For production use, pin to a specific version instead of using @latest to ensure stability: @imagekit/video-player@1.2.3

Quick example

Here's how to set up a basic video player with a single video source.

Copy

<!-- Add video element to your HTML -->
<video id="my-video" class="video-js"></video>

Copy

import { videoPlayer } from '@imagekit/video-player';
import '@imagekit/video-player/styles.css';

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID'
});

player.src({
  src: 'https://ik.imagekit.io/your-imagekit-id/video.mp4'
});

Copy

import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

export default function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID'
  };

  const source = {
    src: 'https://ik.imagekit.io/your-imagekit-id/video.mp4'
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={source}
    />
  );
}

Copy

<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :source="source"
  />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/your-imagekit-id/video.mp4'
};
</script>

Adaptive bitrate streaming example

Enable adaptive bitrate streaming for optimal video quality based on network conditions. The player automatically generates all required streaming representations.

Copy

import { videoPlayer } from '@imagekit/video-player';
import '@imagekit/video-player/styles.css';

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  abs: {
    protocol: 'hls',
    sr: [360, 480, 720, 1080]
  }
});

player.src({
  src: 'https://ik.imagekit.io/your-imagekit-id/video.mp4'
});

Copy

import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

export default function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID',
    abs: {
      protocol: 'hls',
      sr: [360, 480, 720, 1080]
    }
  };

  const source = {
    src: 'https://ik.imagekit.io/your-imagekit-id/video.mp4'
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={source}
    />
  );
}

Copy

<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :source="source"
  />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  abs: {
    protocol: 'hls',
    sr: [360, 480, 720, 1080]
  }
};

const source = {
  src: 'https://ik.imagekit.io/your-imagekit-id/video.mp4'
};
</script>

Why use adaptive bitrate streaming? ABS automatically adjusts video quality based on the viewer's network speed, providing smooth playback without buffering. It delivers the best quality possible for each viewer's connection.

Player configuration

Configure how the player behaves globally, including your ImageKit ID, player features like floating mode and seek thumbnails, default transformations, and standard Video.js settings.

The videoPlayer function accepts three parameters:

Parameter	Description
element `string \| HTMLElement`	Container element where the video player will be initialized. Can be a CSS selector string or a DOM element reference.
options `object`	ImageKit-specific configuration options (see IKPlayer options below).
videoJsOptions `object`	Optional. Standard Video.js options passed directly to the underlying Video.js player instance. See common Video.js options used.

Use the IKVideoPlayer component with the following props:

Copy

import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

export default function App() {
  const ikOptions = {
    // IKPlayer options
  };

  const videoJsOptions = {
    // Video.js options
  };

  const source = {
    // Source options
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      videoJsOptions={videoJsOptions}
      source={source}
    />
  );
}

Prop	Description
ikOptions (required) `object`	ImageKit-specific configuration options (see IKPlayer options below).
videoJsOptions `object`	Optional. Standard Video.js options passed directly to the underlying Video.js player instance. See common Video.js options used.
source `object`	Single video source configuration. See Setting up video source for details.
playlist `object`	Playlist configuration with `sources` array and optional `options` object. See playlist for details.

At least one of source or playlist should be provided for the player to display a video. If both are provided, playlist takes precedence and source is ignored.

Use the IKVideoPlayer component with the following props:

Copy

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  // IKPlayer options
};

const videoJsOptions = {
  // Video.js options
};

const source = {
  // Source options
};
</script>

<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :videoJsOptions="videoJsOptions"
    :source="source"
  />
</template>

Prop	Description
ikOptions (required) `object`	ImageKit-specific configuration options (see IKPlayer options below).
videoJsOptions `object`	Optional. Standard Video.js options passed directly to the underlying Video.js player instance. See common Video.js options used.
source `object`	Single video source configuration. See Setting up video source for details.
playlist `object`	Playlist configuration with `sources` array and optional `options` object. See playlist for details.

At least one of source or playlist should be provided for the player to display a video. If both are provided, playlist takes precedence and source is ignored.

IKPlayer options

ImageKit-specific configuration options for the video player.

Parameter	Description
imagekitId (required) `string`	Your ImageKit ID
floatingWhenNotVisible `'left' \| 'right' \| null`	When enabled, displays a floating player in a corner of the screen when half of the player is visible in the viewport. Use `'right'` to show the floating player in the bottom right corner, or `'left'` for the bottom left corner. Set to `null` to disable. Default: `null`
hideContextMenu `boolean`	Hide right-click context menu. Default: `false`
logo `object`	Configurations to show a clickable logo within the player. Copy { // Default: false showLogo: boolean; // URL of the logo image logoImageUrl: string; // URL to navigate when clicked logoOnclickUrl: string; }
seekThumbnails `boolean`	Enable seek thumbnails on progress bar. Default: `true`
abs `object`	Adaptive bitrate streaming configurations. See Adaptive bitrate streaming for more details. Copy { // Streaming protocol protocol: 'hls' \| 'dash'; // Screen resolutions, e.g., [240, 360, 720, 1080] sr: number[]; } Note: When using ABS, you cannot provide these transformations: `w`, `h`, `ar`, `f`, `vc`, `ac`, and `q`. All other video transformations will work.
transformation `object[]`	Global ImageKit transformations applied to all video sources. Can be overridden per video in the source configuration. Useful for playlists and recommendations to ensure consistent transformations across all videos. See video transformations.
maxTries `number`	The maximum number of times the video player will attempt to request a video. Multiple requests may be necessary if the video is still being processed when it is first requested. Default: `3`
videoTimeoutInMS `number`	The maximum time (in milliseconds) the video player will wait for a video to be available in each video request. This may be relevant if the video is still being processed when it is first requested. Default: `55000`
delayInMS `number`	Delay in milliseconds between retry attempts for failed video requests. Defaults to exponential backoff (10,000ms, 20,000ms, 40,000ms, etc.) if not specified. When set, uses a fixed delay instead. Default: Exponential backoff
signerFn `Function`	A function that generates a signed URL when provided with an ImageKit-powered input URL. Required for private files or when restrict unsigned videos setting is enabled on the account.

VideoJs options

Standard Video.js 8.20.0 options are passed directly to the underlying Video.js player instance. This parameter is optional and allows you to configure native Video.js behavior like player dimensions, autoplay, controls visibility, and playback settings. Common options include controls (boolean), autoplay (boolean or 'muted'), muted (boolean), preload ('auto', 'metadata', or 'none'), width and height (number or string), poster (string URL), fluid and responsive (boolean), playbackRates (array of numbers), and aspectRatio (string like '16:9'). For the complete list of available options, refer to the Video.js documentation.

Common use cases: Most developers use videoJsOptions for basic settings like autoplay: 'muted' for auto-playing videos, fluid: true for responsive sizing, or playbackRates: [0.5, 1, 1.5, 2] for speed controls.

Caution with plugins: Using the plugins option may interfere with ImageKit's video player features. Test thoroughly before deploying to production.

Setting up video source

The player configuration (IKPlayer options and VideoJs options) defines how the player behaves globally - things like your ImageKit ID, floating player settings, and default transformations that apply to all videos. Source options, on the other hand, configure individual videos - their URLs, metadata, poster images, and video-specific transformations. Think of player options as the player's personality, and source options as the content it plays.

Set the video source using player.src():

Copy

// Set source with options object
player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  // ... options
});

// Get current source
const currentSrc = player.src();

Set the video source using the source prop:

Copy

import { IKVideoPlayer } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

function App() {
  const ikOptions = {
    imagekitId: 'YOUR_IMAGEKIT_ID'
  };

  const source = {
    src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
    // ... options
  };

  return (
    <IKVideoPlayer
      ikOptions={ikOptions}
      source={source}
    />
  );
}

Set the video source using the source prop:

Copy

<template>
  <IKVideoPlayer
    :ikOptions="ikOptions"
    :source="source"
  />
</template>

<script setup>
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  // ... options
};
</script>

Source options

Parameter	Description
src (required) `string`	ImageKit-powered URL of the video source
chapters `boolean \| object`	Chapters configuration for dividing videos into sections with markers on the progress bar. Copy // Auto-generate chapters using AI true // Or load from VTT file { url: string } // Or provide time-based chapters (keys are seconds) { [key: number]: string } // Example: { 0: 'Introduction', 30: 'Main content', 60: 'End' }
info `object`	Video metadata displayed in upcoming video preview and playlist widgets. Copy { // Video title title: string; // Video description description: string; }
poster `object`	Poster image configuration. If omitted, ImageKit generates a thumbnail automatically. Copy { // Poster image URL src: string; // ImageKit transformations transformation: object[]; }
abs `object`	Adaptive bitrate streaming configuration for HLS or DASH. See adaptive bitrate streaming for more details. Copy { protocol: 'hls' \| 'dash'; sr: number[]; }
transformation `object[]`	ImageKit transformations to apply to the video. See video transformations.
recommendations `object[]`	Array of recommended videos to display when the video ends. Each item is a source options object. See recommendations.
shoppable `object`	Shoppable video configuration. See shoppable options for more detail.
textTracks `object[]`	Array of text tracks for subtitles and captions. See subtitles & chapters.

Getting the player instance

The player supports all standard Video.js events and methods. Common events include play, pause, ended, timeupdate, and ready. Common methods include play(), pause(), currentTime(), src(), volume(), and muted(). See the Video.js Player API documentation for the complete list.

In JavaScript, the videoPlayer() function returns the player instance directly:

Copy

import { videoPlayer } from '@imagekit/video-player';
import '@imagekit/video-player/styles.css';

const player = videoPlayer('my-video', {
  imagekitId: 'YOUR_IMAGEKIT_ID'
});

// Listen to common events
player.on('play', () => console.log('Playing'));
player.on('pause', () => console.log('Paused'));
player.on('ended', () => console.log('Ended'));
player.on('timeupdate', () => {
  console.log('Time:', player.currentTime());
});

// Use common methods
player.play();
player.pause();
player.currentTime(30); // Seek to 30 seconds

In React, use a ref to access the player instance:

Copy

import { useRef, useEffect } from 'react';
import { IKVideoPlayer } from '@imagekit/video-player/react';
import type { IKVideoPlayerRef } from '@imagekit/video-player/react';
import '@imagekit/video-player/styles.css';

function App() {
  const playerRef = useRef<IKVideoPlayerRef>(null);

  useEffect(() => {
    const checkPlayer = () => {
      const player = playerRef.current?.getPlayer();
      if (player) {
        // Listen to common events
        player.on('play', () => console.log('Playing'));
        player.on('pause', () => console.log('Paused'));
        player.on('ended', () => console.log('Ended'));
        player.on('timeupdate', () => {
          console.log('Time:', player.currentTime());
        });
      } else {
        setTimeout(checkPlayer, 50);
      }
    };
    checkPlayer();
  }, []);

  // Use common methods
  const play = () => playerRef.current?.getPlayer()?.play();
  const pause = () => playerRef.current?.getPlayer()?.pause();
  const seek = (time) => playerRef.current?.getPlayer()?.currentTime(time);

  return (
    <IKVideoPlayer
      ref={playerRef}
      ikOptions={{ imagekitId: 'YOUR_IMAGEKIT_ID' }}
      source={{ src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4' }}
    />
  );
}

In Vue, use a ref to access the player instance:

Copy

<template>
  <IKVideoPlayer
    ref="playerRef"
    :ikOptions="ikOptions"
    :source="source"
  />
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { IKVideoPlayer } from '@imagekit/video-player/vue';
import type { IKVideoPlayerRef } from '@imagekit/video-player/vue';
import '@imagekit/video-player/styles.css';

const playerRef = ref<IKVideoPlayerRef | null>(null);

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const source = {
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4'
};

// Use common methods
const play = () => playerRef.value?.getPlayer()?.play();
const pause = () => playerRef.value?.getPlayer()?.pause();
const seek = (time) => playerRef.value?.getPlayer()?.currentTime(time);

onMounted(() => {
  const checkPlayer = () => {
    const player = playerRef.value?.getPlayer();
    if (player) {
      // Listen to common events
      player.on('play', () => console.log('Playing'));
      player.on('pause', () => console.log('Paused'));
      player.on('ended', () => console.log('Ended'));
      player.on('timeupdate', () => {
        console.log('Time:', player.currentTime());
      });
    } else {
      setTimeout(checkPlayer, 50);
    }
  };
  checkPlayer();
});
</script>

Best practices

Use adaptive bitrate streaming: Enable ABS for better viewer experience across different network conditions. It automatically optimizes quality based on bandwidth.
Optimize video transformations: Apply global transformations at the player level for consistency, and override per-video when needed for specific content requirements.
Enable seek thumbnails: Keep seek thumbnails enabled (default behavior) to help viewers navigate through content quickly.
Pin package versions: In production, use specific version numbers instead of @latest to avoid unexpected breaking changes.
Test player events: Always test video player events (play, pause, ended) in your target browsers to ensure compatibility with your application logic.
Consider floating player: For content-heavy pages with long scrolls, enable floatingWhenNotVisible to keep videos accessible as users browse.
Implement signed URLs: For private or sensitive content, use the signerFn option to secure your video delivery.

Subtitles & chapters: Add subtitles, captions, and chapter markers to your videos
Playlist & recommendations: Create playlists and show video recommendations
Shoppable videos: Make your videos shoppable with product overlays
Adaptive bitrate streaming: Learn more about HLS and MPEG-DASH support
Video transformations: Apply transformations to optimize your videos

Video player

Key features

Installation

Quick example

Adaptive bitrate streaming example

Player configuration

IKPlayer options

VideoJs options

Setting up video source

Source options

Getting the player instance

Best practices

Related features