Skip to main content
Thumbnail resolves and displays a thumbnail image for a given time position. It supports three source formats: VTT text tracks, JSON arrays, and JSON sprite arrays.

​
Import

import { Thumbnail } from '@videojs/react';

​
Basic Usage

​
Text Track (VTT)

Add a <track> with kind="metadata" and label="thumbnails" to your video element. Thumbnail reads the cues automatically via the player store. 
import { Thumbnail } from '@videojs/react';

// Inside your player setup:
<Video src="video.mp4">
  <track
    kind="metadata"
    label="thumbnails"
    src="https://example.com/storyboard.vtt"
    default
  />
</Video>

// Render the thumbnail at a specific time:
<Thumbnail time={12} className="thumbnail-preview" />

​
JSON Thumbnails

Pass a pre-parsed array of thumbnail images directly. This works without Player.Provider. 
import { Thumbnail } from '@videojs/react';

const thumbnails = [
  { url: '/thumb-0.jpg', startTime: 0, endTime: 10 },
  { url: '/thumb-10.jpg', startTime: 10, endTime: 20 },
];

function HoverPreview({ hoverTime }: { hoverTime: number }) {
  return (
    <Thumbnail
      time={hoverTime}
      thumbnails={thumbnails}
      className="hover-preview"
    />
  );
}

​
Props

​
time
number
The media time (in seconds) to resolve a thumbnail for. Defaults to 0.
​
thumbnails
ThumbnailImage[]
Pre-parsed thumbnail images. When provided, bypasses automatic <track> detection. Each item is { url, startTime, endTime? } or { url, startTime, endTime?, width, height, coords } for sprites.
​
crossOrigin
string
CORS attribute passed to the underlying <img> element.
​
loading
"eager" | "lazy"
Loading strategy passed to the underlying <img> element.
​
fetchPriority
"high" | "low" | "auto"
Fetch priority hint passed to the underlying <img> element.
​
className
string | ((state: Thumbnail.State) => string)
CSS class name or a function that receives state and returns a class name.
​
style
CSSProperties | ((state: Thumbnail.State) => CSSProperties)
Inline style or a function that receives state and returns a style object.
​
render
ReactElement | ((props: HTMLProps, state: Thumbnail.State) => ReactElement | null)
Custom render prop for full element control.

​
State Data Attributes

AttributeDescription
data-hiddenPresent when no thumbnail is available for the given time.
data-loadingPresent while the thumbnail image is loading.
data-errorPresent if the thumbnail image failed to load.

​
CSS Styling Example

.thumbnail-preview[data-hidden] {
  display: none;
}

.thumbnail-preview[data-loading] {
  opacity: 0.6;
}

.thumbnail-preview[data-error] {
  outline: 1px solid red;
}

​
Accessibility

Thumbnail is decorative by default (aria-hidden="true"). It is intended for visual preview UX and not primary accessible content.

Build docs developers (and LLMs) love

Get started for freeTalk to us