@videojs/react 10.0.0-beta.24 → 10.0.0-beta.25

package/docs/how-to/installation.md

@@ -4,9 +4,9 @@ Install Video.js and build your first player with streaming support and accessib
 
 Beta Software
 
-Video.js v10 is currently in *beta* . The API may evolve with [feedback🙏](https://github.com/videojs/v10/issues). See the [Changelog](https://github.com/videojs/v10/blob/main/CHANGELOG.md) for recent updates and the [Roadmap](../concepts/v10-roadmap.md) for more details on what’s coming.
+Video.js v10 is currently in *beta*. The API may evolve with [feedback🙏](https://github.com/videojs/v10/issues). See the [Changelog](https://github.com/videojs/v10/blob/main/CHANGELOG.md) for recent updates and the [Roadmap](../concepts/v10-roadmap.md) for more details on what’s coming.
 
-Video.js is a **React video player component library** : composable primitives, hooks, and TypeScript types for building accessible, customizable players with minimal bundle sizes, advanced features, and consistency across browsers.
+Video.js is a **React video player component library**: composable primitives, hooks, and TypeScript types for building accessible, customizable players with minimal bundle sizes, advanced features, and consistency across browsers.
 
 <!-- cli:omit installation -->
 
@@ -19,20 +19,20 @@ bash
 npx @videojs/cli docs how-to/installation \
   --framework <html|react> \
   --preset <video|audio|background-video> \
-  --skin <default|minimal> \
-  --media <html5-video|html5-audio|hls|background-video> \
+  --skin <default|minimal|none> \
+  --media <html5-video|html5-audio|hls|dash|mux-video|mux-audio|vimeo|background-video> \
   --source-url <url> \
   --install-method <cdn|npm|pnpm|yarn|bun>
 ```
 
 Here’s what the flags mean:
 
-*   *Framework* : Pick whether you’re working in React or if you’d like to use HTML custom elements. (More to come!)
-*   *Preset* : Pick a pre-built player. The default presets work well for general website playback.
-*   *Skin* : Pick what your player looks like
-*   *Media* : Pick what kind of media you have
-*   *Source URL* : Define where your media comes from (or omit for a sample URL)
-*   *Install method* : How do you want to install your package? (CDN is HTML-only)
+*   *Framework*: Pick whether you’re working in React or if you’d like to use HTML custom elements. (More to come!)
+*   *Preset*: Pick a pre-built player. The default presets work well for general website playback.
+*   *Skin*: Pick what your player looks like
+*   *Media*: Pick what kind of media you have
+*   *Source URL*: Define where your media comes from (or omit for a sample URL)
+*   *Install method*: How do you want to install your package? (CDN is HTML-only)
 
 If you’re an agent, interview your user and offer to run the CLI for them, or offer them a precomposed CLI command.
 

package/docs/llms.txt

@@ -15,6 +15,7 @@ Installation, project setup, and introductory guides.
 
 Understanding-oriented pages that explain how and why things work. Read these to build a mental model of the library.
 
+- [Google Cast](./concepts/cast.md): How to add Chromecast support to your Video.js player — lazy SDK loading, session lifecycle, and configuration options
 - [Features](./concepts/features.md): The state and actions each feature adds to the player
 - [Skins](./concepts/skins.md): Packaged player designs that include both UI components and their styles.
 - [Presets](./concepts/presets.md): Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.
@@ -34,16 +35,21 @@ API Reference for UI components for building media player interfaces.
 
 - [Player.Provider](./reference/player-provider.md): The state boundary — creates a store and broadcasts it to all descendants.
 - [Player.Container](./reference/player-container.md): The player's interaction surface — handles layout, fullscreen, media attachment, and user activity detection.
+- [AirPlayButton](./reference/airplay-button.md): Accessible AirPlay toggle button that opens the WebKit playback target picker and reflects session state
+- [AudioTrackRadioGroup](./reference/audio-track-radio-group.md): A menu radio group for selecting an audio track
 - [BufferingIndicator](./reference/buffering-indicator.md): Loading indicator that displays when the video player is buffering or waiting for data
 - [CaptionsButton](./reference/captions-button.md): Accessible captions toggle button with availability detection and state reflection
+- [CastButton](./reference/cast-button.md): Accessible Cast toggle button with state reflection and keyboard support
 - [Controls](./reference/controls.md): Container component for composing and auto-hiding video player controls on user interaction
 - [FullscreenButton](./reference/fullscreen-button.md): Accessible fullscreen toggle button with keyboard support and state reflection
+- [Menu](./reference/menu.md): A composable menu component for settings, option selection, and actions
 - [MuteButton](./reference/mute-button.md): Accessible mute/unmute button with keyboard support and volume state reflection
 - [PiPButton](./reference/pip-button.md): Accessible picture-in-picture toggle button with keyboard support and state reflection
 - [PlayButton](./reference/play-button.md): Accessible play/pause button with keyboard support and customizable rendering
 - [PlaybackRateButton](./reference/playback-rate-button.md): A button that cycles through playback speed rates
 - [Popover](./reference/popover.md): A popover component for displaying contextual content anchored to a trigger
 - [Poster](./reference/poster.md): Poster image component that displays a thumbnail until video playback starts
+- [QualityRadioGroup](./reference/quality-radio-group.md): A menu radio group for selecting video quality
 - [SeekButton](./reference/seek-button.md): Accessible seek button for skipping forward or backward by a configurable number of seconds
 - [Slider](./reference/slider.md): A composable slider component with track, fill, thumb, preview, and value parts
 - [Thumbnail](./reference/thumbnail.md): Time-based thumbnail preview component for timeline scrubbing and hover previews
@@ -52,13 +58,26 @@ API Reference for UI components for building media player interfaces.
 - [Tooltip](./reference/tooltip.md): A tooltip component for displaying contextual labels on hover and focus
 - [VolumeSlider](./reference/volume-slider.md): A slider component for controlling media playback volume
 
+## Media Elements
+
+API Reference for media elements that handle streaming protocols and media playback.
+
+- [BackgroundVideo](./reference/background-video.md): Decorative background video element with automatic muting and looping
+- [DashVideo](./reference/dash-video.md): DASH video element powered by dash.js for adaptive bitrate streaming
+- [HlsJsVideo](./reference/hlsjs-video.md): HLS video element powered by hls.js for adaptive bitrate streaming
+- [MuxAudio](./reference/mux-audio.md): Audio element for Mux-hosted HLS streams
+- [MuxVideo](./reference/mux-video.md): Video element for Mux-hosted HLS streams
+- [NativeHlsVideo](./reference/native-hls-video.md): HLS video element using the browser's built-in HLS support
+- [SimpleHlsAudioOnly](./reference/simple-hls-audio-only.md): Audio-only HLS element that plays the audio rendition of an HLS stream
+- [SimpleHlsVideo](./reference/simple-hls-video.md): Lightweight HLS video element with minimal bundle size
+
 ## Hooks & Utilities
 
 API Reference for React hooks and utilities for player integration.
 
 - [createPlayer](./reference/create-player.md): Factory function that creates a player instance with typed store, Provider component, Container, and hooks
 - [Player.usePlayer](./reference/use-player.md): Hook to access the player store from within a Player.Provider
-- [Player.useMedia](./reference/use-media.md): Hook to access the underlying media element from within a Player.Provider
+- [Player.useMedia](./reference/use-media.md): Hook to access the media object from within a Player.Provider
 - [useStore](./reference/use-store.md): Hook to access store state and actions with optional selector-based subscriptions
 ### Advanced
 
@@ -80,9 +99,12 @@ API reference for feature modules that provide player capabilities and state.
 - [Error](./reference/feature-error.md): Media error state and actions for the player store
 - [Fullscreen](./reference/feature-fullscreen.md): Fullscreen state and actions for the player store
 - [Live](./reference/feature-live.md): Live edge state for the player store
+- [Orientation lock](./reference/feature-orientation-lock.md): Screen orientation locking while fullscreen is active
 - [Picture-in-picture](./reference/feature-pip.md): Picture-in-picture state and actions for the player store
 - [Playback](./reference/feature-playback.md): Play/pause state and actions for the player store
 - [Playback rate](./reference/feature-playback-rate.md): Playback speed state and actions for the player store
+- [Quality](./reference/feature-quality.md): Video rendition state and actions for the player store
+- [Audio track](./reference/feature-audio-track.md): Audio track state and actions for the player store
 - [Remote Playback](./reference/feature-remote-playback.md): Remote playback state and actions for the player store
 - [Source](./reference/feature-source.md): Media source state and actions for the player store
 - [Stream type](./reference/feature-stream-type.md): Stream delivery type (live / on-demand) state for the player store

package/docs/reference/airplay-button.md

@@ -0,0 +1,264 @@
+# AirPlayButton
+
+Accessible AirPlay toggle button that opens the WebKit playback target picker and reflects session state
+
+## Anatomy
+
+tsx
+
+```
+<AirPlayButton />
+```
+
+## Behavior
+
+Opens the WebKit AirPlay playback target picker and reflects session state. AirPlay is a WebKit-only feature, so the button reports `availability: "unsupported"` outside Safari (macOS and iOS). On supported platforms availability flips to `"available"` once Safari discovers at least one AirPlay receiver on the local network, and `"unavailable"` otherwise.
+
+The toggle is a no-op unless `availability` is `"available"` — clicking the button while `"unsupported"` or `"unavailable"` will not open the picker. Style the button accordingly (see [Styling](#styling) below) so its appearance matches its actual behavior.
+
+The component consumes the unified [`remotePlayback`](./feature-remote-playback.md) store feature alongside `CastButton`: both buttons drive their state from the same feature, but each only surfaces on its supported platform (WebKit for AirPlay, Chromium for Cast).
+
+WebKit does not expose a `"connecting"` intermediate state — the `state` slice flips directly between `"disconnected"` and `"connected"` when the AirPlay session changes. When connected, the picker itself acts as the disconnect UI.
+
+## Styling
+
+Attribute
+
+Values
+
+Description
+
+`data-airplay-state`
+
+`"disconnected"` | `"connecting"` | `"connected"`
+
+Current AirPlay session state
+
+`data-availability`
+
+`"available"` | `"unavailable"` | `"unsupported"`
+
+Whether AirPlay is reachable on the current platform
+
+Use `data-airplay-state` to swap icons or labels based on the session state:
+
+React renders a `<button>` element. Add a `className` and use it as the selector:
+
+css
+
+```
+/* AirPlay active */
+.airplay-button[data-airplay-state="connected"] {
+  color: var(--accent);
+}
+```
+
+Consider hiding the button on platforms where AirPlay isn’t supported:
+
+css
+
+```
+.airplay-button[data-availability="unsupported"] {
+  display: none;
+}
+```
+
+## Accessibility
+
+Renders a `<button>` with an automatic `aria-label`: “Start AirPlay” when disconnected, “Stop AirPlay” when connected. (The component also supports a `"Connecting"` label, but WebKit AirPlay never emits a `connecting` state, so that label is unreachable in practice.) Override with the `label` prop — either a string or a function that receives the current state. Keyboard activation: Enter / Space.
+
+## Examples
+
+### Basic Usage
+
+AirPlay not supported
+
+App.tsx
+
+App.css
+
+```
+import { AirPlayButton, createPlayer } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="media-container">
+        <Video
+          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
+          autoPlay
+          muted
+          playsInline
+          loop
+        />
+        <AirPlayButton
+          className="media-airplay-button"
+          render={(props, state) => {
+            const label =
+              state.availability === 'unsupported'
+                ? 'AirPlay not supported'
+                : state.state === 'connected'
+                  ? 'Stop AirPlay'
+                  : state.availability === 'unavailable'
+                    ? 'No AirPlay devices found'
+                    : 'Start AirPlay';
+            return <button {...props}>{label}</button>;
+          }}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-airplay-button {
+  position: absolute;
+  right: 10px;
+  bottom: 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);
+}
+
+/* Inactive states: the toggle is a no-op unless availability is "available". */
+.media-airplay-button[data-availability="unavailable"],
+.media-airplay-button[data-availability="unsupported"] {
+  cursor: not-allowed;
+  opacity: 0.5;
+  filter: grayscale(1);
+}
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Whether the button is disabled.
+
+`label`
+
+`string | function`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the button.
+
+Type
+
+`string | ((state: AirPlayButtonState) => string)`
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`state`
+
+`'disconnected' | 'connecting' | 'conn...`
+
+▸
+
+Description
+
+Current AirPlay connection state.
+
+Type
+
+`'disconnected' | 'connecting' | 'connected'`
+
+`availability`
+
+`'available' | 'unavailable' | 'unsupp...`
+
+▸
+
+Description
+
+Whether AirPlay is available on the active platform and media.
+
+Type
+
+`'available' | 'unavailable' | 'unsupported'`
+
+`label`
+
+`string`
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-airplay-state`
+
+`'disconnected' | 'connecting' | 'conn...`
+
+▸
+
+Description
+
+Current AirPlay connection state. @see [https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback/state](https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback/state)
+
+Type
+
+`'disconnected' | 'connecting' | 'connected'`
+
+`data-availability`
+
+`'available' | 'unavailable' | 'unsupp...`
+
+▸
+
+Description
+
+Whether AirPlay is available on the active platform and media. @see [https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback](https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback)
+
+Type
+
+`'available' | 'unavailable' | 'unsupported'`

package/docs/reference/audio-track-radio-group.md

@@ -0,0 +1,59 @@
+# AudioTrackRadioGroup
+
+A menu radio group for selecting an audio track
+
+Creates radio items from the player audio track state and selects the enabled track.
+
+## Anatomy
+
+tsx
+
+```
+const audioTrack = useAudioTrackOptions();
+
+<Menu.RadioGroup value={audioTrack.value} onValueChange={audioTrack.setValue}>
+  <Menu.GroupLabel>Audio</Menu.GroupLabel>
+  {audioTrack.options.map((option) => (
+    <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled}>
+      {option.label}
+      <Menu.ItemIndicator checked={option.value === audioTrack.value} />
+    </Menu.RadioItem>
+  ))}
+</Menu.RadioGroup>
+```
+
+## Behavior
+
+The group is available when the configured media exposes more than one audio track. Labels use the track label, then language, then kind. Pass `formatTrack` to customize the visible labels.
+
+`useAudioTrackOptions` returns `null` when the [audio track feature](./feature-audio-track.md) is not configured. Use the returned options with [`Menu.RadioGroup`](./menu.md).
+
+## Styling
+
+Attribute
+
+Values
+
+Description
+
+`data-audio-track`
+
+`string`
+
+Current audio track value.
+
+`data-disabled`
+
+Present / absent
+
+Present when audio track selection is disabled.
+
+`data-availability`
+
+`"available"` / `"unavailable"`
+
+Whether multiple audio tracks are available.
+
+## Accessibility
+
+The group uses the menu radio group pattern. It receives an accessible label from the `label` prop or defaults to `Audio`.

package/docs/reference/background-video.md

@@ -0,0 +1,76 @@
+# BackgroundVideo
+
+Decorative background video element with automatic muting and looping
+
+Decorative background video. By default it’s muted, looped, and autoplaying — use the opt-out attributes below to change that. Renders a `<video>` inside a shadow DOM, positioned to fill its container.
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { BackgroundVideo } from '@videojs/react/media/background-video';
+
+export default function BasicUsage() {
+  return (
+    <div className="container">
+      <BackgroundVideo src="https://stream.mux.com/601n4w1fq88NJiVpzvrQQeQfNnnjjfKMIN7dCGAEarTs/highest.mp4" />
+    </div>
+  );
+}
+```
+```
+.container {
+  position: relative;
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+## API Reference
+
+### Attributes
+
+Attribute
+
+Description
+
+`src`
+
+URL of the video source.
+
+`nomuted`
+
+Opt out of muted playback. By default the video is muted.
+
+`noloop`
+
+Opt out of looped playback. By default the video loops.
+
+`noautoplay`
+
+Opt out of autoplay. By default the video autoplays.
+
+### CSS Custom Properties
+
+Variable
+
+Default
+
+Description
+
+`–media-object-fit`
+
+`inherit`
+
+Controls how the video fits its container.
+
+`–media-object-position`
+
+`50% 50%`
+
+Controls the position of the video within its container.

package/docs/reference/captions-button.md

@@ -16,6 +16,8 @@ Toggles captions and subtitles on and off. The button checks the media’s text
 
 When no caption or subtitle tracks are present, `data-availability="unavailable"` is set. Use this to hide the button when there are no tracks to toggle.
 
+When `menuTrigger` is enabled and multiple caption or subtitle tracks are available, activation opens the linked captions menu instead of toggling captions directly. React enables `menuTrigger` automatically when a `CaptionsButton` is rendered inside `Menu.Trigger`.
+
 ## Styling
 
 Style the button based on active state:
@@ -41,6 +43,8 @@ media-captions-button[data-availability="unavailable"] {
 
 Renders a `<button>` with an automatic `aria-label`: “Disable captions” when active, “Enable captions” when inactive. Override with the `label` prop. Keyboard activation: Enter / Space.
 
+In menu-trigger mode, the button behaves as a menu trigger and reflects menu state through the trigger attributes.
+
 ## Examples
 
 ### Basic Usage
@@ -145,6 +149,18 @@ Type
 
 `string | ((state: CaptionsButtonState) => string)`
 
+`menuTrigger`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+When true with multiple tracks, pointer activation opens a menu instead of toggling. React sets this automatically inside `Menu.Trigger`.
+
 ### State
 
 State is accessible via the `render`, `className`, and `style` props.