Skip to content

ReferenceMedia

HlsVideo

Lightweight HLS video element with minimal bundle size

The lightweight HLS video element, optimized for minimal bundle size. The hls.js video component is the larger, more compatible alternative.

Import

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

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 />;
}

Cookie-gated streams

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 the engine sends them, the same way the browser does under native playback. Any other value, or no attribute, leaves requests at the platform default and sends no cross-origin cookies.

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.

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

API Reference

Props

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

PropTypeDefaultDetails
crossOrigin'anonymous' | 'use-credentials' | nullnull
disableRemotePlaybackbooleanfalse
preload'' | 'none' | 'metadata' | 'auto'''
sourceobjectnull
srcstring''
streamType'on-demand' | 'live' | 'unknown''unknown'

Refs

ref

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

const ref = useRef<HTMLVideoElement>(null);

<HlsVideo ref={ref} />

mediaRef

Receives the HlsVideoAdapter 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 { HlsVideoAdapter } from '@videojs/spf/hls-video';

const mediaRef = useRef<HlsVideoAdapter>(null);

<HlsVideo 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.