@videojs/react 10.0.0-rc.1 → 10.0.0-rc.3

package/docs/reference/components/mute-button.md

@@ -0,0 +1,200 @@
+# MuteButton
+
+Accessible mute/unmute button with keyboard support and volume state reflection
+
+## Import
+
+```tsx
+import { MuteButton } from '@videojs/react';
+```
+
+## Anatomy
+
+```tsx
+<MuteButton />
+```
+
+## Behavior
+
+Toggles mute on and off, and exposes a derived `volumeLevel` based on the current volume and mute state.
+
+Mute availability is separate from volume-level availability because some media can accept a mute command without supporting volume changes.
+
+When mute is unavailable or unsupported, the component returns `null`. Toggling is also ignored while mute is unavailable.
+
+## Styling
+
+| Attribute | Values | Description |
+| --- | --- | --- |
+| `data-muted` | Present / absent | Present when the media is muted |
+| `data-volume-level` | `"off"` \| `"low"` \| `"medium"` \| `"high"` | Current volume level |
+| `data-availability` | `"available"` \| `"unavailable"` \| `"unsupported"` | Whether the media can be muted |
+| `data-hidden` | Present / absent | Present on the HTML element while mute is unavailable or unsupported |
+
+Style the button based on muted state:
+
+React renders a `<button>` element. Add a `className` to style it:
+
+```css
+.mute-button[data-muted] .icon-muted { display: inline; }
+.mute-button:not([data-muted]) .icon-unmuted { display: inline; }
+```
+
+Use `data-volume-level` for multi-level icon switching:
+
+```css
+.mute-button[data-volume-level="off"] .icon-off { display: inline; }
+.mute-button[data-volume-level="low"] .icon-low { display: inline; }
+.mute-button[data-volume-level="medium"] .icon-medium { display: inline; }
+.mute-button[data-volume-level="high"] .icon-high { display: inline; }
+```
+
+Unavailable and unsupported buttons are hidden automatically. No availability selector or extra hiding CSS is required.
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label`: “Unmute” when muted, “Mute” when unmuted. Override with the `label` prop. Keyboard activation: Enter / Space.
+
+## Examples
+
+### Basic Usage
+
+**App.tsx**
+
+```tsx
+import { Container, createPlayer, MuteButton } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
+        <MuteButton
+          className="media-mute-button"
+          render={(props, state) => <button {...props}>{state.muted ? 'Unmute' : 'Mute'}</button>}
+        />
+      </Container>
+    </Player>
+  );
+}
+```
+
+**App.css**
+
+```css
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-mute-button {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  padding-block: 8px;
+  padding-inline: 20px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+```
+
+### Volume Levels
+
+**App.tsx**
+
+```tsx
+import { Container, createPlayer, MuteButton } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function VolumeLevels() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
+        <MuteButton
+          className="media-mute-button"
+          render={(props, state) => (
+            <button {...props}>
+              {state.volumeLevel === 'off'
+                ? 'Off'
+                : state.volumeLevel === 'low'
+                  ? 'Low'
+                  : state.volumeLevel === 'medium'
+                    ? 'Medium'
+                    : 'High'}
+            </button>
+          )}
+        />
+      </Container>
+    </Player>
+  );
+}
+```
+
+**App.css**
+
+```css
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-mute-button {
+  position: absolute;
+  bottom: 10px;
+  left: 10px;
+  padding-block: 8px;
+  padding-inline: 20px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.7);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+```
+
+## API Reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | Whether the button is disabled. |
+| `label` | `{ key: string; text: string } \| string \| ((state: MuteButtonState) => Text \| string)` | `''` | Custom label for the button. |
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `muted` | `boolean` | Whether audio is muted. |
+| `label` | `{ key: string; text: string } \| string` | |
+| `volumeLevel` | `'off' \| 'low' \| 'medium' \| 'high'` | Derived volume level:<br>- `off`: muted or volume is 0<br>- `low`: volume < 0.5<br>- `medium`: volume < 0.75<br>- `high`: volume >= 0.75 |
+| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether the media can be muted at all. |
+| `hidden` | `boolean` | Whether the button is hidden because the media has no mute to toggle. |
+
+### Data attributes
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `data-muted` | — | Present when the media is muted. |
+| `data-volume-level` | `'off' \| 'low' \| 'medium' \| 'high'` | Indicates the volume level. |
+| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Indicates mute availability (`available`, `unavailable`, `unsupported`). |
+| `data-hidden` | — | Present when the button is hidden because the media has no mute to toggle. |

package/docs/reference/components/mux-audio.md

@@ -0,0 +1,93 @@
+# MuxAudio
+
+Audio element for Mux-hosted HLS streams
+
+Audio element for playing Mux-hosted HLS streams. Built on hls.js with Mux-specific optimizations.
+
+## Import
+
+```bash
+pnpm add @videojs/mux-audio
+```
+
+```tsx
+import { MuxAudio } from '@videojs/react/media/mux-audio';
+```
+
+## Analytics and casting
+
+The Mux audio component plays Mux streams. It doesn’t monitor them or cast them — [Mux Data](../../guides/mux-data.md) and [Google Cast](../../guides/casting.md) are separate extensions you add to the player alongside it. Mux Data needs no environment key here, since Mux attributes the views to the environment that owns the playback ID:
+
+Install both extensions before using the example below:
+
+```bash
+pnpm add @videojs/mux-data @videojs/google-cast
+```
+
+```tsx
+import { GoogleCast } from '@videojs/react/extensions/google-cast';
+import { MuxAudio } from '@videojs/react/media/mux-audio';
+import { MuxData } from '@videojs/react/extensions/mux-data';
+
+<MuxAudio source={{ playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM' }} />
+<MuxData playerSoftwareName="mux-audio" />
+<GoogleCast />
+```
+
+- [Mux Data — metadata, options, and configuration](../../guides/mux-data.md)
+- [Cast to AirPlay and Chromecast](../../guides/casting.md)
+
+## Examples
+
+### Basic Usage
+
+**App.tsx**
+
+```tsx
+import { MuxAudio } from '@videojs/react/media/mux-audio';
+
+export default function BasicUsage() {
+  return <MuxAudio className="mux-audio" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" crossOrigin="anonymous" controls />;
+}
+```
+
+**App.css**
+
+```css
+.mux-audio {
+  width: 100%;
+  height: 54px;
+}
+```
+
+## API Reference
+
+### Props
+
+Accepts the standard React props for a native `<audio>`, plus these Video.js-specific props:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disableRemotePlayback` | `unknown` | `false` | Whether remote playback (AirPlay, Google Cast) is disabled for this media. |
+| `preload` | `MediaPreloadType` | `'metadata'` | Preload type (`'none'` / `'metadata'` / `'auto'`). |
+| `source` | `{ type?: 'application/vnd.apple.mpegurl' \| 'video/mp4'; preferPlayback?: 'mse' \| 'native'; maxAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; capRenditionToPlayerSize?: boolean; minAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; engine?: HlsEngineConfig; src?: string; playbackId?: string; customDomain?: string; playback?: MuxPlaybackParams; poster?: MuxPosterParams; storyboard?: MuxStoryboardParams; drm?: MuxDrmParams } \| null` | `null` | Structured Mux source. Setting it derives `src` from the playback ID, custom domain, and `playback` params (appended as `snake_case` query params). A `playback.token` replaces all other params — signed URLs bake them into the token. Engine options live under `engine`. A `drm.token` fills in `drm` itself: Mux's FairPlay, Widevine, and PlayReady license servers for this playback ID, so protected media plays whichever path the browser takes. License servers named alongside the token win, key by key, for content Mux does not license. `playback.maxResolution` and `playback.minResolution` are server-side: they decide which renditions Mux puts in the manifest at all. The inherited `maxAutoResolution` and `minAutoResolution` only look like their pair — those are client-side and bound which of the renditions that *do* arrive adaptive selection reaches for. The two halves are independent. |
+| `src` | `string` | `''` | Media source URL. Setting a Mux stream URL (`https://stream.mux.com/<playback-id>.m3u8?...`) extracts the playback ID and query params into `source`; other URLs are kept as a plain `source.src`. Only playback options carry over. Mux identity comes from the URL, and the signed `poster`, `storyboard`, and `drm` tokens are scoped to a playback ID, so carrying them onto a different source would build rejected URLs. |
+| `streamType` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | Current stream type (`'on-demand'` / `'live'` / `'unknown'`). |
+
+### Engine options
+
+#### `source.engine.nativeHls`
+
+Options passed under `source.engine.nativeHls`.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `drmSystems` | `Partial<Record<KeySystem, DrmSystemConfig>> \| undefined` | 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. |
+
+### Ref
+
+Forwards its ref to the rendered `<audio>`. The ref is an [HTMLAudioElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement) and exposes its complete native property and method API.
+
+### 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`.

package/docs/reference/components/mux-background-video.md

@@ -0,0 +1,30 @@
+# MuxBackgroundVideo
+
+Mux-specific name for the HLS background video component
+
+MuxBackgroundVideo is the Mux-specific name for [HlsBackgroundVideo](./hls-background-video.md). The two names use the same implementation and API.
+
+Use this name when your source is a Mux HLS URL and the Mux identity makes the composition easier to read. See [Add a background video](../../guides/background-video.md) to compare the background-video options.
+
+## Import
+
+```tsx
+import { MuxBackgroundVideo } from '@videojs/react/media/mux-background-video';
+```
+
+## Load a Mux source
+
+Pass a complete Mux HLS URL through `src`. This component does not take a playback ID or structured `source` object. Use Mux delivery query parameters to limit which renditions Mux includes in the manifest:
+
+```tsx
+<MuxBackgroundVideo
+  src="https://stream.mux.com/PLAYBACK_ID.m3u8?max_resolution=720p"
+  crossOrigin="anonymous"
+/>
+```
+
+MuxBackgroundVideo does not create a poster or preview thumbnails, and it does not send analytics data. Keep the poster in your page and add analytics separately when you need them.
+
+## API
+
+The source, error, and fixed playback behavior are identical to [HlsBackgroundVideo](./hls-background-video.md).

package/docs/reference/components/mux-data.md

@@ -0,0 +1,43 @@
+# MuxData
+
+Options for the Mux Data extension that monitors playback quality
+
+Adds the [Mux Data](https://data.mux.com) [extension](../../guides/architecture.md) to the player’s media. It renders nothing — place it inside the player as a sibling of the media element. See [Mux Data](../../guides/mux-data.md) for how monitoring works.
+
+## Import
+
+```bash
+pnpm add @videojs/react @videojs/mux-data
+```
+
+```tsx
+import { MuxData } from '@videojs/react/extensions/mux-data';
+```
+
+## Anatomy
+
+```tsx
+<MuxData />
+```
+
+## Options
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `envKey` | `string` | Mux Data environment key the beacons are sent to. Optional for Mux-hosted playback |
+| `metadata` | `object` | Mux Data metadata for the view |
+| `playerSoftwareName` | `string` | Player name reported to Mux Data |
+| `playerSoftwareVersion` | `string` | Player version reported to Mux Data. Defaults to the Video.js version |
+| `playerInitTime` | `number` | Epoch milliseconds the player was initialized. Defaults to when the component was created |
+| `beaconCollectionDomain` | `string` | Custom domain the beacons are sent to |
+| `disableCookies` | `boolean` | Stops the SDK from setting cookies |
+| `debug` | `boolean` | Turns on SDK debug logging |
+| `MuxDataSdk` | `object` | SDK used for monitoring. Set it to `undefined` to switch monitoring off |
+
+Changing `MuxDataSdk`, `beaconCollectionDomain`, `debug`, or `disableCookies` restarts monitoring, which ends the current view and starts a new one. The rest update the view in place.
+
+## See also
+
+- [Mux Data](../../guides/mux-data.md): How monitoring works
+- [Mux video reference](./mux-video.md)
+- [Mux audio reference](./mux-audio.md)

package/docs/reference/components/mux-video.md

@@ -0,0 +1,183 @@
+# MuxVideo
+
+Video element for Mux-hosted HLS streams
+
+Video element for playing Mux-hosted HLS streams. Built on hls.js with Mux-specific optimizations.
+
+## Import
+
+```bash
+pnpm add @videojs/mux-video
+```
+
+```tsx
+import { MuxVideo } from '@videojs/react/media/mux-video';
+```
+
+## Load a source
+
+The `source` param builds the URL for you from a playback ID, an optional custom domain, and `playback` params. Playback params are just camelCased [Mux playback query params](https://www.mux.com/docs/api-reference/stream/streaming/get-hls-manifest); for example, `max_resolution` becomes `maxResolution`.
+
+```tsx
+<MuxVideo
+  source={{ 
+    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
+    customDomain: 'media.example.com',
+    playback: { maxResolution: '1080p' }
+  }} 
+/>
+```
+
+If for some reason you need a bit more control, you can use the `src` param with a plain ’ol URL, too:
+
+```tsx
+<MuxVideo
+  src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
+/>
+```
+
+MuxVideo ignores the same source object when it is assigned again. A new object fires `sourcechange` even when its values are equal, although an equivalent playback source does not reload.
+
+## Posters and storyboards
+
+The Mux video component derives a poster image and a storyboard from the playback ID. `source.poster` and `source.storyboard` configure the generated URLs.
+
+When the Mux video component is inside a player, it supplies the poster for the skin to display. Set `poster` on the player when you want to use your own image instead.
+
+A generated poster becomes available after MuxVideo mounts. Pass `poster` to the player when the image must appear in server-rendered HTML.
+
+The Mux video component injects the derived storyboard `<track>` automatically and removes it when the media detects a live stream. Configure the derived URLs through the source object:
+
+```tsx
+<MuxVideo
+  source={{
+    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
+    poster: { time: 2, width: 1280 },
+    storyboard: { format: 'webp' },
+  }}
+/>
+```
+
+The storyboard lives on a Mux domain, so the Mux video component has to be CORS-enabled for that cross-origin `<track>` to load at all. The [thumbnail component](./thumbnail.md) then fetches the sprite sheets its cues point at the same way:
+
+```tsx
+<MuxVideo
+  source={{ playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM' }}
+  crossOrigin="anonymous"
+/>
+```
+
+## Signed playback
+
+For [signed playback](https://www.mux.com/docs/guides/secure-video-playback), put the playback token on `source.playback.token`. The token replaces every other playback param, so bake modifiers like resolution and time bounds into the token when you sign it.
+
+Signed playback needs a separate token for each image URL. Put the thumbnail token (`aud: 't'`) at `source.poster.token` and the storyboard token (`aud: 's'`) at `source.storyboard.token`. If either token is missing or has the wrong audience, the Mux video component does not generate the corresponding URL.
+
+```tsx
+<MuxVideo
+  source={{
+    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
+    playback: { token: playbackToken },
+    poster: { token: posterToken },
+    storyboard: { token: storyboardToken },
+  }}
+/>
+```
+
+## Analytics and casting
+
+The Mux video component plays Mux streams. It doesn’t monitor them or cast them — [Mux Data](../../guides/mux-data.md) and [Google Cast](../../guides/casting.md) are separate extensions you add to the player alongside it. Mux Data needs no environment key here, since Mux attributes the views to the environment that owns the playback ID:
+
+Install both extensions before using the example below:
+
+```bash
+pnpm add @videojs/mux-data @videojs/google-cast
+```
+
+```tsx
+import { createPlayer } from '@videojs/react';
+import { GoogleCast } from '@videojs/react/extensions/google-cast';
+import { MuxData } from '@videojs/react/extensions/mux-data';
+import { MuxVideo } from '@videojs/react/media/mux-video';
+import { videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export function MuxPlayer() {
+  return (
+    <Player>
+      <MuxVideo source={{ playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM' }} playsInline />
+      <MuxData playerSoftwareName="mux-video" />
+      <GoogleCast />
+    </Player>
+  );
+}
+```
+
+- [Mux Data](../../guides/mux-data.md): Metadata, options, and configuration
+- [Cast to AirPlay and Chromecast](../../guides/casting.md): Receivers, load requests, and session state
+
+## Examples
+
+### Basic Usage
+
+**App.tsx**
+
+```tsx
+import { MuxVideo } from '@videojs/react/media/mux-video';
+
+export default function BasicUsage() {
+  return (
+    <MuxVideo
+      className="mux-video"
+      src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
+      autoPlay
+      muted
+      playsInline
+      loop
+      crossOrigin="anonymous"
+    />
+  );
+}
+```
+
+**App.css**
+
+```css
+.mux-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 | Description |
+| --- | --- | --- | --- |
+| `disableRemotePlayback` | `unknown` | `false` | Whether remote playback (AirPlay, Google Cast) is disabled for this media. |
+| `preload` | `MediaPreloadType` | `'metadata'` | Preload type (`'none'` / `'metadata'` / `'auto'`). |
+| `source` | `{ type?: 'application/vnd.apple.mpegurl' \| 'video/mp4'; preferPlayback?: 'mse' \| 'native'; maxAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; capRenditionToPlayerSize?: boolean; minAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; engine?: HlsEngineConfig; src?: string; playbackId?: string; customDomain?: string; playback?: MuxPlaybackParams; poster?: MuxPosterParams; storyboard?: MuxStoryboardParams; drm?: MuxDrmParams } \| null` | `null` | Structured Mux source. Setting it derives `src` from the playback ID, custom domain, and `playback` params (appended as `snake_case` query params). A `playback.token` replaces all other params — signed URLs bake them into the token. Engine options live under `engine`. A `drm.token` fills in `drm` itself: Mux's FairPlay, Widevine, and PlayReady license servers for this playback ID, so protected media plays whichever path the browser takes. License servers named alongside the token win, key by key, for content Mux does not license. `playback.maxResolution` and `playback.minResolution` are server-side: they decide which renditions Mux puts in the manifest at all. The inherited `maxAutoResolution` and `minAutoResolution` only look like their pair — those are client-side and bound which of the renditions that *do* arrive adaptive selection reaches for. The two halves are independent. |
+| `src` | `string` | `''` | Media source URL. Setting a Mux stream URL (`https://stream.mux.com/<playback-id>.m3u8?...`) extracts the playback ID and query params into `source`; other URLs are kept as a plain `source.src`. Only playback options carry over. Mux identity comes from the URL, and the signed `poster`, `storyboard`, and `drm` tokens are scoped to a playback ID, so carrying them onto a different source would build rejected URLs. |
+| `streamType` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | Current stream type (`'on-demand'` / `'live'` / `'unknown'`). |
+
+### Engine options
+
+#### `source.engine.nativeHls`
+
+Options passed under `source.engine.nativeHls`.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `drmSystems` | `Partial<Record<KeySystem, DrmSystemConfig>> \| undefined` | 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. |
+
+### Ref
+
+Forwards its ref to the rendered `<video>`. The ref is an [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) and exposes its complete native property and method API.
+
+### 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`.

package/docs/reference/components/native-hls-video.md

@@ -0,0 +1,78 @@
+# 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](./hlsjs-video.md) instead.
+
+## Import
+
+```tsx
+import { NativeHlsVideo } from '@videojs/react/media/native-hls-video';
+```
+
+## Examples
+
+### Basic Usage
+
+**App.tsx**
+
+```tsx
+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 />;
+}
+```
+
+**App.css**
+
+```css
+.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 | Description |
+| --- | --- | --- | --- |
+| `preload` | `MediaPreloadType` | `'metadata'` | Preload type (`'none'` / `'metadata'` / `'auto'`). |
+| `source` | `{ src?: string; drm?: Partial<Record<KeySystem, DrmSystemConfig>>; engine?: NativeHlsEngineConfig } \| null` | `null` | 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. |
+| `src` | `string` | `''` | 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'` | 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](../../guides/media-sources.md) covers how engine options fit into a structured source.
+
+```tsx
+<NativeHlsVideo
+  source={{
+    src: 'https://example.com/playlist.m3u8',
+    engine: {
+      nativeHls: {
+        drmSystems: { 'com.apple.fps': { licenseUrl: 'https://example.com/license' } },
+      },
+    },
+  }}
+/>
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `drmSystems` | `Partial<Record<KeySystem, DrmSystemConfig>> \| undefined` | 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. |
+
+### Ref
+
+Forwards its ref to the rendered `<video>`. The ref is an [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) and exposes its complete native property and method API.
+
+### 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`.