ReferenceMedia

NativeHlsVideo

HLS video element using the browser's built-in HLS support

HLS video element that relies on the browser’s native HLS support. Works on Safari and other browsers with built-in HLS playback. For cross-browser HLS support, use the hls.js video component instead.

Import

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

Load a source

src takes an HLS manifest URL, which the browser plays with its own HLS support.

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

The structured source object adds drm and engine options to the URL. Setting source derives src.

Protected content

source.drm names your license servers, keyed by EME key system id.

<NativeHlsVideo
  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' },
    },
  }}
/>

The browser’s own HLS licenses FairPlay only, so the com.apple.fps entry is the one this component uses. Media sources covers DRM in more depth.

Examples

Basic Usage

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

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

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

API Reference

Props

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

Prop	Type	Default
`preload`	`MediaPreloadType`	`'metadata'`
Description Preload type (`'none'` / `'metadata'` / `'auto'`).
`source`	`object`	`null`
Description Structured source: what to play (`src`) plus how to play it (`engine.nativeHls`). Assigning it derives `src`. Only a new URL reaches the element, so reassigning an equivalent source neither reloads nor disturbs key exchange. Use `src` or `load()` to reload what is already playing. Changing this source does not emit `sourcechange`. When the hls.js media component uses native HLS playback, it emits its own `sourcechange` and forwards the native playback events. Type `{ src?: string; drm?: Partial<Record<KeySystem, DrmSystemConfig>>; engine?: NativeHlsEngineConfig } \| null`
`src`	`string`	`''`
Description Media source URL. Assigning it replaces the identity half of `source` and leaves `engine` intact, so changing the URL never disturbs key exchange. Like the element's own `src`, assigning it always loads — including the URL already playing.
`streamType`	`'on-demand' \| 'live' \| 'unknown'`	`'unknown'`
Description Current stream type (`'on-demand'` / `'live'` / `'unknown'`).

Engine options

`source.engine.nativeHls`

This element hands playback to the browser, so there’s no JavaScript engine to configure. This carries the one thing native playback still needs from you. Media Sources covers how engine options fit into a structured source.

<NativeHlsVideo
  source={{
    src: 'https://example.com/playlist.m3u8',
    engine: {
      nativeHls: {
        drmSystems: { 'com.apple.fps': { licenseUrl: 'https://example.com/license' } },
      },
    },
  }}
/>

Option	Type	Details
`drmSystems`	`Partial<Record<KeySystem, DrmSystemCo...`
Description License servers for protected content, keyed by EME key system id. An escape hatch for licensing native playback differently from every other path: naming it replaces `source.drm` here, and nowhere else. Type `Partial<Record<KeySystem, DrmSystemConfig>> \| undefined`

Refs

`ref`

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

const ref = useRef<HTMLVideoElement>(null);

<NativeHlsVideo ref={ref} />

`mediaRef`

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

const mediaRef = useRef<NativeHlsAdapter>(null);

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