media-thumbnail

Time-based thumbnail preview component for timeline scrubbing and hover previews

Quick Start: Video Track

Thumbnail can read thumbnail cues directly from your video track. Add a <track> with kind="metadata" and label="thumbnails" to your media element.

Mux provides this as storyboard.vtt:

https://image.mux.com/{PLAYBACK_ID}/storyboard.vtt

<Video src="video.mp4">
  <track
    kind="metadata"
    label="thumbnails"
    src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt"
    default
  />
</Video>
<Thumbnail time={12} />

<video src="video.mp4">
  <track
    kind="metadata"
    label="thumbnails"
    src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt"
    default
  />
</video>
<media-thumbnail time="12"></media-thumbnail>

Anatomy

<media-thumbnail time="12"></media-thumbnail>

Behavior

Thumbnail resolves an image for the current time.

Supported source formats:

Text track: <track kind="metadata" label="thumbnails" src="...vtt">
JSON array: { url, startTime, endTime? }[]
JSON sprite array: { url, startTime, endTime?, width, height, coords }[]

In React, text-track mode needs Player because it reads track state from the player store. JSON modes (thumbnails prop) work without a player.

The component picks the latest thumbnail whose startTime is less than or equal to the current time, then scales/clips sprite tiles to fit CSS min/max constraints while preserving aspect ratio.

Styling

Use state data attributes for pure CSS styling:

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

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

media-thumbnail[data-error] {
  outline: 1px solid #ef4444;
}

React renders a <div> element. Add a className to style it:

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

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

.thumbnail[data-error] {
  outline: 1px solid #ef4444;
}

Accessibility

Thumbnail is decorative by default (aria-hidden="true"). It is intended for visual preview UX (for example, timeline hover previews) rather than primary accessible content.

Examples

Text Track (VTT)

import { Container, createPlayer, Thumbnail } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function TextTrackUsage() {
  return (
    <Player>
      <Container className="demo">
        <Video
          className="media"
          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
          preload="auto"
          muted
          playsInline
          crossOrigin="anonymous"
        >
          <track kind="metadata" label="thumbnails" src="/docs/demos/thumbnail/basic.vtt" default />
        </Video>
        <Thumbnail className="media-thumbnail" time={12} />
      </Container>
    </Player>
  );
}

.demo {
  position: relative;
  max-width: 280px;
}

.media {
  position: absolute;
  width: 1px;
  height: 1px;
  pointer-events: none;
  opacity: 0;
}

.media-thumbnail {
  display: block;
  width: auto;
  min-width: 0;
  max-width: 240px;
}

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

<section class="demo">
    <video-player>
        <media-container>
            <video
                class="media"
                src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
                preload="auto"
                muted
                playsinline
                crossorigin="anonymous"
            >
                <track
                    kind="metadata"
                    label="thumbnails"
                    src="/docs/demos/thumbnail/basic.vtt"
                    default
                />
            </video>
            <media-thumbnail class="media-thumbnail" time="12"></media-thumbnail>
        </media-container>
    </video-player>
</section>

.demo {
  position: relative;
  display: block;
  max-width: 280px;
}

.media {
  position: absolute;
  width: 1px;
  height: 1px;
  pointer-events: none;
  opacity: 0;
}

.media-thumbnail {
  display: block;
  width: auto;
  min-width: 0;
  max-width: 240px;
}

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

import '@videojs/html/video/player';
import '@videojs/html/ui/thumbnail';

JSON Array

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

const THUMBNAILS = [
  {
    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg?time=0',
    startTime: 0,
    endTime: 10,
  },
  {
    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg?time=10',
    startTime: 10,
    endTime: 20,
  },
  {
    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg?time=20',
    startTime: 20,
  },
];

export default function JsonUsage() {
  return <Thumbnail thumbnails={THUMBNAILS} time={12} style={{ maxWidth: 240 }} />;
}

<media-thumbnail time="12" style="max-width: 240px;"></media-thumbnail>

import '@videojs/html/ui/thumbnail';

type DemoThumbnailImage = {
  url: string;
  startTime: number;
  endTime?: number;
};

type ThumbnailDemoElement = HTMLElement & { thumbnails?: DemoThumbnailImage[] };

const thumbnail = document.querySelector<ThumbnailDemoElement>('media-thumbnail');
if (thumbnail) {
  thumbnail.thumbnails = [
    {
      url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg?time=0',
      startTime: 0,
      endTime: 10,
    },
    {
      url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg?time=10',
      startTime: 10,
      endTime: 20,
    },
    {
      url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg?time=20',
      startTime: 20,
    },
  ];
}

JSON Sprite Array

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

const THUMBNAILS = [
  {
    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.jpg',
    startTime: 0,
    endTime: 10,
    width: 284,
    height: 160,
    coords: { x: 0, y: 0 },
  },
  {
    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.jpg',
    startTime: 10,
    endTime: 20,
    width: 284,
    height: 160,
    coords: { x: 284, y: 0 },
  },
  {
    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.jpg',
    startTime: 20,
    width: 284,
    height: 160,
    coords: { x: 568, y: 0 },
  },
];

export default function JsonSpriteUsage() {
  return <Thumbnail thumbnails={THUMBNAILS} time={12} style={{ maxWidth: 240 }} />;
}

<media-thumbnail time="12" style="max-width: 240px;"></media-thumbnail>

import '@videojs/html/ui/thumbnail';

type DemoThumbnailImage = {
  url: string;
  startTime: number;
  endTime?: number;
  width?: number;
  height?: number;
  coords?: { x: number; y: number };
};

type ThumbnailDemoElement = HTMLElement & { thumbnails?: DemoThumbnailImage[] };

const thumbnail = document.querySelector<ThumbnailDemoElement>('media-thumbnail');
if (thumbnail) {
  thumbnail.thumbnails = [
    {
      url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.jpg',
      startTime: 0,
      endTime: 10,
      width: 284,
      height: 160,
      coords: { x: 0, y: 0 },
    },
    {
      url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.jpg',
      startTime: 10,
      endTime: 20,
      width: 284,
      height: 160,
      coords: { x: 284, y: 0 },
    },
    {
      url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.jpg',
      startTime: 20,
      width: 284,
      height: 160,
      coords: { x: 568, y: 0 },
    },
  ];
}

API Reference

Props

Prop	Type	Default
`crossOrigin`	`'anonymous' \| 'use-credentials' \| '' ...`	`—`
Attribute `cross-origin` Description CORS setting forwarded to the inner `<img>`. Left unset, this follows the media element: a cross-origin thumbnail `<track>` only loads when the media is CORS-enabled, so the sprite sheets its cues point at are fetched with that same mode. Pass `null` to opt out and fetch them without CORS. Thumbnails supplied directly never inherit, since they need not be related to the media element at all. `''` is a value like any other, read as Anonymous by the CORS-settings attribute rules — it does not opt out. Type `'anonymous' \| 'use-credentials' \| '' \| null`
`fetchPriority`	`'high' \| 'low' \| 'auto'`	`—`
Attribute `fetch-priority` Description Image fetch priority hint forwarded to the inner `<img>`.
`loading`	`'eager' \| 'lazy'`	`—`
Attribute `loading` Description Image loading strategy forwarded to the inner `<img>`.
`time`	`number`	`—`
Attribute `time` Description Time in seconds to display the thumbnail for.

State

State is accessible via the render, className, and style props.

State is reflected as data attributes for CSS styling.

Property	Type	Details
`loading`	`boolean`
Description The thumbnail image is loading.
`error`	`boolean`
Description The thumbnail image failed to load.
`hidden`	`boolean`
Description Whether the component is hidden because no thumbnail is available and it is not loading.

Data attributes

Attribute	Type	Details
`data-loading`
`data-error`
`data-hidden`