Playlist & recommendations

Create engaging video experiences with playlists that play multiple videos in sequence, or show personalized recommendations when a video ends. Both features help keep viewers engaged and increase watch time.

Playlist

Playlists let you queue multiple videos with a scrollable widget that viewers can use to navigate between videos. Perfect for tutorial series, episodic content, or curated collections.

Loading video player...

Tip: Use the info property in source options to provide titles and descriptions for each video. These appear in the playlist widget and upcoming video previews.

Playlist Setup

The player.playlist() method accepts a sources array and options object.

Copy

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

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

const playlistManager = player.playlist({
  sources: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video1.mp4',
      // ... Rest of the SourceOptions
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video2.mp4'
    }
  ],
  options: {
    autoAdvance: 3, // Auto-advance after 3 seconds
    repeat: true, // Loop playlist
    presentUpcoming: 10, // Show "next up" 10 seconds before end
    widgetProps: {
      direction: 'vertical' // or 'horizontal'
    }
  }
});

// Load and play the first video
playlistManager.loadFirstItem();

The playlist prop accepts a sources array and options object.

Copy

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

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

  const playlist = {
    sources: [
      {
        src: 'https://ik.imagekit.io/<your-imagekit-id>/video1.mp4',
        // ... Rest of the SourceOptions
      },
      {
        src: 'https://ik.imagekit.io/<your-imagekit-id>/video2.mp4'
      }
    ],
    options: {
      autoAdvance: 3,
      repeat: true,
      presentUpcoming: 10,
      widgetProps: {
        direction: 'vertical' // or 'horizontal'
      }
    }
  };

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

The playlist prop accepts a sources array and options object.

Copy

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

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

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID'
};

const playlist = {
  sources: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video1.mp4',
      // ... Rest of the SourceOptions
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video2.mp4'
    }
  ],
  options: {
    autoAdvance: 3,
    repeat: true,
    presentUpcoming: 10,
    widgetProps: {
      direction: 'vertical' // or 'horizontal'
    }
  }
};
</script>

Parameter	Description
sources `object[]`	Array of video sources. See Source options for more details.
options `object`	Playlist configuration options (see Playlist options below).

Playlist options

Parameter	Description
autoAdvance `number \| false`	Number of seconds to wait before automatically advancing to the next video, or `false` to disable auto-advance. Set to `0` to advance immediately when the current video ends.
repeat `boolean`	Automatically restart the playlist from the beginning when it reaches the end. Default: `false`
presentUpcoming `boolean \| number`	Display a thumbnail preview of the upcoming video. Set to `true` to show 10 seconds before the current video ends, or specify a number for a custom delay in seconds.
widgetProps `object`	Configuration options for the playlist widget. Copy { // Position of the widget relative to the player direction: 'vertical' \| 'horizontal'; } Default: `{ direction: 'vertical' }` (widget on the right side; use `'horizontal'` to display below the player)

Playlist manager methods

After calling player.playlist(options), you get a PlaylistManager instance with the following methods:

Method	Description
loadFirstItem() `boolean`	Set the first video in the playlist as the current source (does not start playback). Returns `true` if successfully set, `false` otherwise.
loadNextItem() `boolean`	Set the next video in the playlist as the current source (does not start playback). Returns `true` if successfully set, `false` otherwise.
loadPreviousItem() `boolean`	Set the previous video in the playlist as the current source (does not start playback). Returns `true` if successfully set, `false` otherwise.
playAtIndex(index: number) `void`	Play a specific video in the playlist by index (0-based).
playNext() `void`	Play the next video in the playlist.
playPrevious() `void`	Play the previous video in the playlist.
getItems() `object[]`	Get an array of all playlist items. Returns an array of Source options objects.
autoAdvanceDelay(delay?: number \| false) `number \| null \| void`	Get or set the auto-advance delay. Get if no parameter, set if parameter provided. Return values: `null` → auto-advance disabled/not configured `0` → enabled with immediate advance (no delay) `> 0` → enabled, wait N seconds

Recommendations

Recommendations display suggested videos when the current video ends, encouraging viewers to continue watching. Great for suggesting related content, next episodes, or personalized picks.

Loading video player...

Recommendations setup

Add recommendation sources to the recommendations array when configuring the video source. Each recommendation source is a Source options object.

Copy

player.src({
  src: 'https://ik.imagekit.io/<your-imagekit-id>/video.mp4',
  recommendations: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video2.mp4',
      info: { title: 'Recommended Video 1' },
      // ... Rest of the SourceOptions
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video3.mp4',
      info: { title: 'Recommended Video 2' }
    }
  ]
});

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',
    recommendations: [
      {
        src: 'https://ik.imagekit.io/<your-imagekit-id>/video2.mp4',
        info: { title: 'Recommended Video 1' },
        // ... Rest of the SourceOptions
      },
      {
        src: 'https://ik.imagekit.io/<your-imagekit-id>/video3.mp4',
        info: { title: 'Recommended Video 2' }
      }
    ]
  };

  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',
  recommendations: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video2.mp4',
      info: { title: 'Recommended Video 1' },
      // ... Rest of the SourceOptions
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video3.mp4',
      info: { title: 'Recommended Video 2' }
    }
  ]
};
</script>

Recommendations in playlists

If you explicitly specify recommendations for sources in your playlist and autoAdvance is false, those recommendations are displayed in the recommendations pane. If a viewer selects one of the recommendations, they exit the playlist context.

Copy

const playlistManager = player.playlist({
  sources: [
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video1.mp4',
      info: { title: 'Video 1' },
      recommendations: [
        {
          src: 'https://ik.imagekit.io/<your-imagekit-id>/video4.mp4',
          info: { title: 'Recommended after Video 1' }
        }
      ]
    },
    {
      src: 'https://ik.imagekit.io/<your-imagekit-id>/video2.mp4',
      info: { title: 'Video 2' }
    }
  ],
  options: {
    autoAdvance: false // Disable auto-advance to show recommendations
  }
});

Note: When autoAdvance is enabled in playlists, recommendations are not shown because the player automatically moves to the next video in the queue.

Best practices

Add video metadata: Always include info.title and info.description for playlist videos. This helps viewers understand what's coming next and makes the playlist widget more informative.
Use appropriate auto-advance timing: Set autoAdvance to 3-5 seconds to give viewers time to decide if they want to continue or choose a different video. Setting it to 0 works well for seamless playlists.
Enable upcoming previews: Use presentUpcoming: 10 to show what's next 10 seconds before the current video ends, giving viewers a smooth transition.
Choose the right widget direction: Use direction: 'vertical' for desktop-focused experiences with wide screens, and direction: 'horizontal' for mobile-friendly layouts.
Limit recommendation count: Show 3-5 recommendations maximum. Too many choices can overwhelm viewers and reduce engagement.
Leverage playlist manager: Use playlistManager.getItems() and playlistManager.playAtIndex() to build custom navigation or chapter selection interfaces.
Combine with global transformations: Apply consistent transformations at the player level to ensure all playlist videos have uniform quality and formatting.

Video player overview: Learn about basic video player setup and source configuration
Subtitles & chapters: Add text tracks and chapter markers to playlist videos
Shoppable videos: Make playlist videos shoppable with product overlays
Video transformations: Apply transformations consistently across all playlist videos

Copy

Playlist & recommendations

Playlist

Playlist Setup

Playlist options

Playlist manager methods

Recommendations

Recommendations setup

Recommendations in playlists

Best practices

Related features