1. Providers
  2. HLS



This provider is used to embed streamable video content into documents using the native <video> element, and supports streaming media using the HTTP Live Streaming (HLS) protocol.


You'll need to install hls.js if you're using the HLS provider locally (e.g., not over a CDN):

        npm i hls.js




You can provide a type hint if you're loading the HLS playlist over a proxy like so:


Loading hls.js

The HLS provider will default to loading hls.js from JSDelivr. We load the default bundle in development, and the minified version in production.


You can point library at any URL that re-exports hls.js@^1.0. This means you can use your own server or CDN if desired.

Importing hls.js

You can also load hls.js by statically, or dynamically importing it and setting the library property on the provider like so:


Load Events

The provider will fire the following events on <media-player> while loading hls.js:

  • hls-lib-load-start: Fired when we begin downloading the library.
  • hls-lib-loaded: Fired when the library has been loaded.
  • hls-lib-load-error: Fired when the library fails to download.

These events are fired regardless of how you decide to load the library (i.e., import or CDN).

Configuring hls.js

You can configure hls.js using the config property on the provider like so:



You can obtain a reference to the hls.js instance like so:



All hls.js events can be listened to directly off the <media-player> component. Some examples include:

  • Hls.Events.MEDIA_ATTACHED -> hls-media-attached
  • Hls.Events.MANIFEST_LOADED -> hls-manifest-loaded
  • Hls.Events.LEVEL_SWITCHING -> hls-level-switching

All HLS event types are prefixed with HLS and end with Event like so:

        import {
  type HLSLevelSwitchingEvent,
  type HLSManifestLoadedEvent,
  type HLSMediaAttachedEvent,
} from 'vidstack';


You can find a complete list of HLS events in the <media-player> API reference.

Video Element

You can obtain a reference to the underlying HTMLVideoElement element like so:


Event Target

The HTMLVideoElement can also be referenced on all media events like so: