Skip to content

ReferenceMedia

LazyVideo

Unstable

Video media that picks the media component for its source and loads only that component's code

Reads src, renders the media component that plays it, and loads that component’s code only once the source is known. A page playing an MP4 loads no engine; a page playing DASH loads dash.js and nothing else.

Import

npm install @videojs/react @videojs/hlsjs-video @videojs/dash-video @videojs/mux-video @videojs/youtube-video @videojs/vimeo-video @videojs/wistia-video @videojs/cloudflare-video @videojs/tiktok-video @videojs/playerjs-video
import { LazyVideo } from '@videojs/react/media/lazy-video';

Install every engine package listed: your bundler resolves each media component LazyVideo can load, so a missing one fails the build. Each engine still lands in its own chunk, which downloads only when a source needs it. To install fewer, build your own from just the media you need.

Sources

Source Resolves to Loads
.mp4, .webm, .mov, .ogv, and audio files Native <video> Nothing
HLS HlsJsVideo hls.js
HLS where there’s no MSE NativeHlsVideo Native HLS support
stream.mux.com MuxVideo Mux Video
DASH (.mpd) DashVideo dash.js
YouTube YouTubeVideo The YouTube embed
Vimeo VimeoVideo The Vimeo embed
Wistia WistiaVideo The Wistia player
Cloudflare Stream CloudflareVideo The Cloudflare Stream embed
TikTok TikTokVideo The TikTok embed
player.js embeds marked with ?playerjs PlayerJsVideo The service’s player.js embed

Sources are matched by the hosts and shorthands resolveAdapterType recognizes, then by MIME type or file extension. A media file on one of these hosts, such as a direct Vimeo MP4, plays as that file. A source that matches none of these renders nothing and logs an error in development.

player.js is a protocol any embed can speak, so nothing in an embed’s URL says it’s one. Add a playerjs query parameter to choose the player.js media, such as https://streamable.com/e/moo?playerjs. It takes precedence over the host and file extension, and the player.js media removes it before loading the embed.

Behavior

The media component starts loading as soon as src is set. It doesn’t wait for the player to scroll into view. The resolved media plays with preload="none" unless you set preload yourself.

Changing src to a source the same media plays updates that media in place. Changing it to a source that needs a different media replaces the media once the new one has loaded.

Until the media loads, nothing is rendered in its place, so give the player an aspect ratio, as the installation snippet does, and its box stays the same size while the media loads and when src swaps it for another. Without one, the player takes its height from the media once it renders.

Set type to the source’s MIME type when its URL has no file extension, such as a signed URL. type only chooses the media; it isn’t passed on.

Set source instead of src to give the media its structured source, with options beyond the URL. Its src and type choose the media as src and type do, and a Mux playbackId or a Wistia mediaId chooses the Mux or Wistia media without a URL. The resolved media takes the whole object as its source; a native <video> takes only its src. While source is set, src and type are ignored.

<LazyVideo source={{ playbackId: 'a4nOgmxGWg6gULfcBbAa00gXyfcwPnAFldF8RdsNyk8M' }} />

Keep the source object stable across renders, as a constant or with useMemo; a new object reloads the media.

HLS plays through hls.js wherever the browser has MSE, Safari included, so it has the same features everywhere. Only a browser without MSE, such as iOS before 17.1, plays it natively. Set preferPlayback to 'native' to play HLS natively wherever the browser can, or to 'mse' to always play it through hls.js. It’s also passed on to the resolved hls.js or Mux media, on its source, so a Mux stream follows the same preference.

Every other prop, including ref, mediaRef, event handlers, and children, is passed to the resolved media, so switching to that component directly only changes the import. Each media accepts the props it understands; embeds ignore fallback.

During server rendering, files render their <video>. HLS renders nothing until the browser can be asked whether it plays HLS natively, so the server and client choose the same component.

Custom media

createLazyVideo builds a LazyVideo from a list of media, tried in order. Each built-in media has its own import, so the list decides which engine packages need to be installed. Put your own media first to take sources from the built-in ones.

import { createLazyVideo } from '@videojs/react/media/lazy/create';
import { hlsjsVideo } from '@videojs/react/media/lazy/hlsjs-video';
import { nativeHlsVideo } from '@videojs/react/media/lazy/native-hls-video';
import { video } from '@videojs/react/media/lazy/video';

// Module level, so the media it loads keep their identity across renders.
const AcmeLazyVideo = createLazyVideo([
  {
    match: ({ url }) => url?.hostname === 'video.acme.com',
    load: () => import('./acme-video').then((m) => m.AcmeVideo),
  },
  video,
  nativeHlsVideo,
  hlsjsVideo,
]);

A media gives match and either load, for a component whose code should download only once a source needs it, or component, for one that’s cheap to ship up front. Set fallback: true when the component renders fallback content inside a <video> or <audio>, preferPlayback: true when its adapter, which it hands to mediaRef, takes preferPlayback on its source, as HlsJsVideo and MuxVideo do, and source: true when the component takes a structured source prop. Without it, a source reaches the component as src.

match receives the source worked out once for every media:

Field Type Description
src string The trimmed source URL; empty for a structured source that names its media by id.
type string | undefined The MIME type the source was given.
url URL | null src parsed as a URL, or null for a path or bare id.
adapterType AdapterType | null The kind of source, with the names resolveAdapterType returns, such as 'hls' or 'youtube'.
playback 'native' | 'mse' | undefined How HLS should play here, after preferPlayback. undefined while it isn’t known, such as during server rendering.
source LazyMediaSource | null The structured source it was resolved from, if any, for media that match on more than the URL.

Return true to play the source, or undefined when the media can’t tell yet; it isn’t chosen until it can, and nothing after it is tried.

The built-in media are video, nativeHlsVideo, hlsjsVideo, dashVideo, muxVideo, youtubeVideo, vimeoVideo, wistiaVideo, cloudflareVideo, tiktokVideo, and playerJsVideo, each imported from media/lazy/ plus its kebab-case name.

Lazy loading one known media

LazyVideo is for sources you don’t know ahead of time. When you already know which media plays the source, load that media’s own entry lazily instead: no source matching, and only its code.

import { VideoPlayer, VideoSkin } from '@videojs/react/video';
import { lazy, Suspense } from 'react';

// Module level, so the component keeps its identity across renders.
const VimeoVideo = lazy(() =>
  import('@videojs/react/media/vimeo-video').then((m) => ({ default: m.VimeoVideo }))
);

export function Player() {
  return (
    <VideoPlayer>
      <VideoSkin>
        <Suspense fallback={null}>
          <VimeoVideo src="https://vimeo.com/76979871" />
        </Suspense>
      </VideoSkin>
    </VideoPlayer>
  );
}

The media registers with the player when it mounts, and ref, mediaRef, and useMedia() work as they do with a static import.

Until the media loads, the player has no media, so its controls show their empty state.

Examples

Basic Usage

import { LazyVideo } from '@videojs/react/media/lazy-video';
import { useState } from 'react';

import './BasicUsage.css';

const SOURCES = [
  { label: 'MP4', src: 'https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4' },
  { label: 'HLS', src: 'https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8' },
  { label: 'DASH', src: 'https://dash.akamaized.net/akamai/streamroot/050714/Spring_4Ktest.mpd' },
  { label: 'YouTube', src: 'https://www.youtube.com/watch?v=aqz-KE-bpKQ' },
];

export default function BasicUsage() {
  const [src, setSrc] = useState(SOURCES[0]!.src);

  return (
    <div className="react-lazy-video-basic">
      <LazyVideo className="react-lazy-video-basic__media" src={src} controls muted playsInline />
      <div className="react-lazy-video-basic__sources">
        {SOURCES.map((source) => (
          <button key={source.label} type="button" aria-pressed={source.src === src} onClick={() => setSrc(source.src)}>
            {source.label}
          </button>
        ))}
      </div>
    </div>
  );
}

API Reference

Prop Type Default Description
src string Source URL. Its host or file extension chooses the media.
type string MIME type of the source. Takes precedence over the file extension.
source LazyMediaSource Structured source, in place of src and type. Chooses the media by its src, type, playbackId, or mediaId, and is passed on as the media’s source.
preferPlayback 'native' | 'mse' Playback path for HLS: 'native' wherever the browser can, 'mse' always through hls.js. Unset, through hls.js wherever there’s MSE, and native only where there’s none. Also passed on to hls.js and Mux media.
preload 'none' | 'metadata' | 'auto' | '' 'none' How much the resolved media loads before playback.