Adding Preview Thumbnails

JW Player supports the loading of preview thumbnails for individual shots or scenes in a video. These thumbnails are displayed in a tooltip when a viewer hovers the controlbar. This allows for quick scanning and navigating of longer-form content. Here is an example player with tooltip thumbnails:


This guide explains how to format and embed these Tooltip Thumbnails.

Note: This is not supported on mobile.


JW Player uses WebVTT files to load Tooltip Thumbnails. WebVTT is a plain text format, part of the HTML5 standard, that's also used for providing closed captioning. When used for thumbnails, these VTT files contain links to the actual thumbnail images, which can be in JPG, PNG or GIF format.

VTT Example

Here is an example VTT file. It belongs to a 20-second video, for which 4 preview thumbnails are included:


00:00.000 --> 00:05.000

00:05.000 --> 00:10.000

00:10.000 --> 00:15.000

00:15.000 --> 00:20.000

The structure of the VTT file is quite straightforward. It consist of a list of cues, which each include:

  • The range the tooltip thumbnail represents. Note the range needs to be in (HH:)MM:SS.MMM format. Only this exact notation will be parsed.
  • The URL to the tooltip thumbnail for this range. The URL is relative to the VTT file (not to the page or player), much like images included in CSS sheets.

Note JW Player will render the thumbnails in the tooltip using their original dimensions. We think thumbnails that are around 100 to 150 pixels wide tend to work well. Smaller thumbnails are hard to decipher and larger thumbnails are too much of a distraction to the main content.

Using Sprites

For many reasons (file sizes, load delays, server requests, etc.), having each thumbnail be a separate image is sub-optimal. Therefore, JW Player supports so-called Thumbnail Sprites, multiple thumbnails stitched together into a single image. Here's an example:

A Tooltip Thumbnail Sprite

In the VTT file, the individual thumbnails can be identified by appending their coordinates to the thumbnail URL using a spatial Media Fragment:


00:00.000 --> 00:05.000

00:05.000 --> 00:10.000

00:10.000 --> 00:15.000

00:15.000 --> 00:20.000

Note JW Player to date only supports pixel-based fragments, not percentage-based ones.


Tooptip Thumbnail VTT files can be embedded in a player by adding it as a track to the Playlist Object. The tooltip thumbnails track has 2 required properties:

URL to the WebVTT file that refers to the thumbnails (e.g. /assets/myThumbnails.vtt).
The type of text track we are using. For thumbnails, specify thumbnails here. Otherwise, this will default to captions.

Note that tracks in JW Player have two additional properties, default and label. Both are only used for Closed Captions, and ignored for Tooltip Thumbnails.


Here is an example setup, loading a single video with Tooltip Thumbnails:

var playerInstance = jwplayer("myElement");
    playlist: [{
        file: "/assets/myVideo.mp4",
        image: "/assets/myPoster.jpg",
        tracks: [{ 
            file: "/assets/myThumbnails.vtt", 
            kind: "thumbnails"

Note that VTT files are subject to cross-domain security restrictions and therefore won't automatically load from another domain than the player. See Crossdomain File Loading for more info.

RSS Feeds

When using external RSS playlists, Tooltip Thumbnails can be included using a <jwplayer:track> element. Here is an example feed, containing the same video and thumbnail track as above:

<rss version="2.0" xmlns:media="" > 

      <description>Sintel is a fantasy CGI from the Blender Open Movie Project.</description>
      <jwplayer:source file="/assets/myVideo.mp4" />
      <jwplayer:track file="/assets/myThumbnails.vtt" kind="thumbnails" />


See the RSS Feed Embed example for more info.

Did you find this article helpful?

Please log in to rate this article.