Skip to content

ReferenceMedia

HlsJsVideo

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

HLS video element powered by hls.js for adaptive bitrate streaming, with full feature support across every browser. It’s more compatible than the lightweight HLS video component, which is smaller and covers most HLS playback. For browser-native playback, see the native HLS video component.

Import

pnpm add @videojs/hlsjs-video
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';

Load a source

src takes an HLS manifest URL.

<HlsJsVideo src="https://example.com/playlist.m3u8" />

The structured source object says what to play and how to play it: type for a manifest URL without an .m3u8 extension, preferPlayback to choose between hls.js ('mse') and the browser’s own HLS ('native'), the adaptive resolution caps, drm, and engine options. Setting source derives src. Media sources explains each option.

<HlsJsVideo
  source={{
    src: 'https://example.com/manifest',
    type: 'application/vnd.apple.mpegurl',
    preferPlayback: 'mse',
    maxAutoResolution: '1080p',
  }}
/>

Protected content

source.drm names your license servers, keyed by EME key system id. Name every system you hold a license server for: which one gets negotiated is the browser’s choice.

<HlsJsVideo
  source={{
    src: 'https://example.com/protected.m3u8',
    drm: {
      'com.apple.fps': {
        licenseUrl: 'https://example.com/fairplay',
        serverCertificateUrl: 'https://example.com/fairplay.cer',
      },
      'com.widevine.alpha': { licenseUrl: 'https://example.com/widevine' },
    },
  }}
/>

hls.js receives every system named here. When the browser’s own HLS plays the stream, only the com.apple.fps entry applies. Media sources covers what each path can license and how to configure hls.js’s DRM directly.

A stream on another origin that is gated by cookies — CloudFront signed cookies, for example — needs those cookies on every manifest and segment request, or the CDN answers 403. Set the standard crossorigin="use-credentials" on the element and hls.js sends them (withCredentials on its XHR loader, credentials: 'include' on its fetch loader), the same way the browser does under native playback. Any other value, or no attribute, leaves hls.js’s default and sends no cross-origin cookies. An xhrSetup or fetchSetup you pass through source.engine.hlsJs still runs, after this, on the same request.

The CDN must answer with Access-Control-Allow-Credentials: true and a specific Access-Control-Allow-Origin, not *, or the browser refuses the credentialed response.

<HlsJsVideo src="https://cdn.example.com/stream.m3u8" crossOrigin="use-credentials" />

Examples

Basic Usage

import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';

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

API Reference

Props

Accepts the standard React props for a native <video>, plus these Video.js-specific props:

PropTypeDefaultDetails
disableRemotePlaybackunknownfalse
preloadMediaPreloadType'metadata'
sourceobjectnull
srcstring''
streamType'on-demand' | 'live' | 'unknown''unknown'

Engine options

source.engine.nativeHls

When playback falls back to the browser’s own HLS, hls.js isn’t involved and its options don’t apply. This configures that path instead.

OptionTypeDetails
drmSystemsPartial<Record<KeySystem, DrmSystemCo...

Refs

ref

Forwards to the rendered <video>, an HTMLVideoElement with its complete native property and method API.

const ref = useRef<HTMLVideoElement>(null);

<HlsJsVideo ref={ref} />

mediaRef

Receives the HlsJsAdapter that drives the <video>, the same object useMedia() returns inside a player. It forwards the native media methods, properties, and events, such as play() and currentTime, and exposes the playback engine through engine. It is set once the adapter has attached to the element and cleared when the element unmounts. For DOM-only APIs, use ref.

import type { HlsJsAdapter } from '@videojs/hlsjs-video';

const mediaRef = useRef<HlsJsAdapter>(null);

<HlsJsVideo mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();

Events

Handle standard media events with React event props such as onPlay and onTimeUpdate. For native events without a React prop, attach a listener through the ref with addEventListener.