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';

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 same HTMLVideoElement as ref. Embed components hand their playback adapter to mediaRef instead, so code that works with several media components can read the playback object from one prop.

const mediaRef = useRef<HTMLVideoElement>(null);

<NativeHlsVideo mediaRef={mediaRef} />

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.