ReferenceMedia
LazyVideo
UnstableVideo 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
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
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.
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.
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:
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.
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.