HlsVideo

HLS video element powered by hls.js for adaptive bitrate streaming

HLS video element powered by hls.js for adaptive bitrate streaming. It’s the recommended choice for HLS playback: full feature support across every browser. For alternatives, see NativeHlsVideo (browser-native HLS) or SimpleHlsVideo (lightweight HLS).

Examples

Basic Usage

import { HlsVideo } from '@videojs/react/media/hls-video';

export default function BasicUsage() {
  return (
    <HlsVideo
      className="hls-video"
      src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
      autoPlay
      muted
      playsInline
      loop
    />
  );
}

.hls-video {
  width: 100%;
  aspect-ratio: 16 / 9;
}

<media-container class="media-container">
    <hls-video
        src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
        autoplay
        muted
        playsinline
        loop
    ></hls-video>
</media-container>

.media-container {
  position: relative;
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
}

import '@videojs/html/media/container';
import '@videojs/html/media/hls-video';

API Reference

Host Properties

Property	Type	Default
`audioRenditions`	`AudioRenditionListLike \| undefined`	`—`
Description Read-only. Selectable audio variants, populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
`audioTracks`	`AudioTrackListLike \| undefined`	`—`
Description Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
`config`	`HlsMediaConfig`	`{}`
Description Playback configuration: a preferred playback path, an explicit content type, and options forwarded to hls.js. Reassigning reloads the engine when an engine-relevant option changes.
`engine`	`Hls \| null`	`—`
Description Read-only. Underlying playback engine — the hls.js `Hls` instance when playing via MSE, otherwise `null`. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods.
`error`	`(ErrorLike & MediaError) \| null`	`—`
Description Read-only.
`liveEdgeStart`	`number`	`—`
Description Read-only. Presentation time marking the start of the Live Edge Window. Derived from the delegate on every read; `NaN` when no delegate is attached or the stream is not live.
`preload`	`PreloadType`	`'metadata'`
Description Preload type (`'none'` / `'metadata'` / `'auto'`).
`src`	`string`	`''`
`streamType`	`StreamType`	`'unknown'`
Description Current stream type (`'on-demand'` / `'live'` / `'unknown'`).
`targetLiveWindow`	`number`	`—`
Description Read-only. Seekable range size for live content. `0` for standard live, `Infinity` for DVR, `NaN` for on-demand or unknown. Fires `targetlivewindowchange` when the value changes (bridged from the delegate).
`videoRenditions`	`VideoRenditionListLike \| undefined`	`—`
Description Read-only. Selectable quality levels, populated only while the hls.js (MSE) engine is active; otherwise `undefined`.
`videoTracks`	`VideoTrackListLike \| undefined`	`—`
Description Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`.

Attributes

Renders a native <video> element and accepts these media attributes as React props. The standard ones behave as described in the MDN media attributes reference: autopictureinpictureautoPlaycontrolscontrolslistcrossOrigindisablepictureinpicturedisableremoteplaybackloadingloopmutedplaysInlineposterpreloadsrcstream-type

Events

Handle these media events with React event props (e.g. onPlay, onTimeUpdate). See media events: abortcanplaycanplaythroughdurationchangeemptiedendederrorloadeddataloadedmetadataloadstartpauseplayplayingprogressratechangeresizeseekedseekingstalledsuspendtimeupdatevolumechangewaiting

These media events have no React prop — attach a listener through a ref with addEventListener: addtrackchangeenterpictureinpictureleavepictureinpictureremovetrack

Beyond the media events above, this element emits:

Event	Description
`streamtypechange`	Fired when the detected stream type changes. Read `streamType` for the new value.
`targetlivewindowchange`	Fired when the target live window changes. Read `targetLiveWindow` for the new value.

These events have no built-in React prop. Attach a listener to the element through a ref with addEventListener.

Methods

Supports these methods from the native media API. See HTMLMediaElement for the core methods: addTextTrackcanPlayTypeexitFullscreenexitPictureInPictureloadpauseplayrequestFullscreenrequestPictureInPicture

In React, call these through a ref to the element.

CSS Custom Properties

Variable	Details
`--media-video-border-radius`
Description Border radius of the video element.
`--media-object-fit`
Description Object fit for the video.
`--media-object-position`
Description Object position for the video.
`--media-caption-track-duration`
Description Duration of the caption track transition.
`--media-caption-track-delay`
Description Delay before the caption track transition.
`--media-caption-track-y`
Description Vertical offset of the caption track.