ReferenceMedia
lazy-video
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.
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 attribute, except id, class, style, slot, and part, is copied to the resolved media element, which <lazy-video> renders as its child. <track> and <source> children present when the media is created move into it; add later ones to the media element directly. <lazy-video> lays out as its child does, so a skin sizes it the same way as the element it resolves to. An embed fills the player, and falls back to 16:9 in a player with no height of its own.
Custom media
createLazyVideoElement builds a <lazy-video> class from a list of media, tried in order, to register under a tag of your own. 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, the tag of the element that plays its sources, and load to register that element once a source needs it. Leave load out for an element that’s built in or already registered. Set preferPlayback: true when the element takes preferPlayback on its source, as <hlsjs-video> and <mux-video> do.
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.
Write the media element in the page, and import its module when you want it to load:
The import defines <vimeo-video>, and the browser upgrades the element in place: it reads the attributes already on it and registers with the player. Set attributes rather than properties before the import; a property set on an element that isn’t defined yet hides the element’s own property once it is.
Until the media loads, the player has no media, so its controls show their empty state.