# LazyVideo

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

> **Caution: Unstable API**
>
> This API works today, but its shape is still settling and may change in a minor release. The implementation underneath is production quality; what is not final is how you configure it from Video.js. Pin your version and check the changelog when you upgrade.

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

```bash
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
```

```tsx
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](#custom-media) from just the media you need.

## Sources

| Source | Resolves to | Loads |
| --- | --- | --- |
| `.mp4`, `.webm`, `.mov`, `.ogv`, and audio files | Native `<video>` | Nothing |
| HLS | [HlsJsVideo](https://videojs.org/docs/framework/react/reference/components/hlsjs-video) | hls.js |
| HLS where there’s no MSE | [NativeHlsVideo](https://videojs.org/docs/framework/react/reference/components/native-hls-video) | Native HLS support |
| `stream.mux.com` | [MuxVideo](https://videojs.org/docs/framework/react/reference/components/mux-video) | Mux Video |
| DASH (`.mpd`) | [DashVideo](https://videojs.org/docs/framework/react/reference/components/dash-video) | dash.js |
| YouTube | [YouTubeVideo](https://videojs.org/docs/framework/react/reference/components/youtube-video) | The YouTube embed |
| Vimeo | [VimeoVideo](https://videojs.org/docs/framework/react/reference/components/vimeo-video) | The Vimeo embed |
| Wistia | [WistiaVideo](https://videojs.org/docs/framework/react/reference/components/wistia-video) | The Wistia player |
| Cloudflare Stream | [CloudflareVideo](https://videojs.org/docs/framework/react/reference/components/cloudflare-video) | The Cloudflare Stream embed |
| TikTok | [TikTokVideo](https://videojs.org/docs/framework/react/reference/components/tiktok-video) | The TikTok embed |
| player.js embeds marked with `?playerjs` | [PlayerJsVideo](https://videojs.org/docs/framework/react/reference/components/playerjs-video) | The service’s player.js embed |

Sources are matched by the hosts and shorthands [`resolveAdapterType`](https://videojs.org/docs/framework/react/reference/api/resolve-adapter-type) 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.

```tsx
<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.

```tsx
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`](https://videojs.org/docs/framework/react/reference/api/resolve-adapter-type) 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.

```tsx
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

**App.tsx**

```tsx
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>
  );
}
```

**App.css**

```css
.react-lazy-video-basic {
  display: grid;
  gap: 12px;
  width: 100%;
}

.react-lazy-video-basic__media {
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
  background: #000;
}

.react-lazy-video-basic__sources {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}

.react-lazy-video-basic__sources button[aria-pressed="true"] {
  font-weight: 600;
}
```

## 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. |

---

React documentation: https://videojs.org/docs/framework/react/llms.txt
All documentation: https://videojs.org/llms.txt
