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

package/docs/how-to/installation.md

@@ -0,0 +1,170 @@
+# Installation
+
+Install Video.js and build your first player with streaming support and accessible controls
+
+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 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 -->
+
+
+This guide has code examples tailored to your use case. To generate this guide with tailored code examples, run `npx @videojs/cli docs how-to/installation`. If you run it without flags, it will allow you to interactively configure your player. Or, you can run it with flags:
+
+bash
+
+```
+npx @videojs/cli docs how-to/installation \
+  --framework <html|react> \
+  --preset <video|audio|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)
+
+If you’re an agent, interview your user and offer to run the CLI for them, or offer them a precomposed CLI command.
+
+
+<!-- /cli:omit installation -->
+
+If your user’s requirements can’t be met by a preset/skin, [eject](./customize-skins.md) and customize an existing preset/skin for your needs. As you develop with Video.js, rely heavily on [llms.txt](../llms.txt) to make sure you always have the latest information.
+
+<!-- cli:replace installation -->
+
+
+## Install Video.js
+
+npm
+
+pnpm
+
+yarn
+
+bun
+
+```
+npm install @videojs/react
+```
+
+```
+pnpm add @videojs/react
+```
+
+```
+yarn add @videojs/react
+```
+
+```
+bun add @videojs/react
+```
+
+## Create your player
+
+Add it to your components folder in a new file.
+
+./components/player/index.tsx
+
+```
+'use client';
+
+import '@videojs/react/video/skin.css';
+import { createPlayer, videoFeatures } from '@videojs/react';
+import { VideoSkin, Video } from '@videojs/react/video';
+
+const Player = createPlayer({ features: videoFeatures });
+
+interface MyPlayerProps {
+  src: string;
+}
+
+export const MyPlayer = ({ src }: MyPlayerProps) => {
+  return (
+    <Player.Provider>
+      <VideoSkin>
+        <Video src={src} playsInline />
+      </VideoSkin>
+    </Player.Provider>
+  );
+};
+```
+
+## Use your player
+
+./app/page.tsx
+
+```
+import { MyPlayer } from '../components/player';
+
+export const HomePage = () => {
+  return (
+    <div>
+      <h1>Welcome to My App</h1>
+      <MyPlayer src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" />
+    </div>
+  );
+};
+```
+
+
+
+
+
+
+
+
+<!-- /cli:replace installation -->
+
+## CSP
+
+If your application uses a Content Security Policy, you may need to allow additional sources for player features to work correctly.
+
+### Common requirements
+
+*   `media-src` must allow your media URLs.
+*   `img-src` must allow any poster or thumbnail image URLs.
+*   `connect-src` must allow HLS manifests, playlists, captions, and segment requests when using HLS playback.
+*   `media-src blob:` is required when using the HLS player variants, which use MSE-backed playback.
+*   `worker-src blob:` is required when using the `hls.js` player variants.
+*   `style-src 'unsafe-inline'` is currently required for some player UI and HTML player styling behavior.
+
+### Example
+
+http
+
+```
+Content-Security-Policy:
+  script-src 'self';
+  style-src 'self' 'unsafe-inline';
+  img-src 'self' https: data: blob:;
+  media-src 'self' https: blob:;
+  connect-src 'self' https:;
+  worker-src 'self' blob:;
+```
+
+## See also
+
+[
+
+Skins
+
+Some skins expose CSS custom properties
+
+](../concepts/skins.md)
+
+* * *
+
+That’s it! You now have a fully functional Video.js player. Go forth and play.
+
+Something not quite right? You can [submit an issue](https://github.com/videojs/v10/issues) and ask for help, or explore [other support options](/html5-video-support).

package/docs/llms.txt

@@ -0,0 +1,113 @@
+# Video.js v10 — React Documentation
+
+## Getting started
+
+Installation, project setup, and introductory guides.
+
+- [Installation](./how-to/installation.md): Install Video.js and build your first player with streaming support and accessible controls
+- [Why Video.js?](./concepts/why-videojs.md): The open-source video player for React and HTML. Lightweight, accessible components built for performance and streaming.
+- [Overview](./concepts/overview.md): How Video.js players are structured — state, UI, and media
+- [Build with AI](./how-to/build-with-ai.md): How to give AI tools the context they need to build Video.js players alongside you
+- [v10 Roadmap](./concepts/v10-roadmap.md): Timeline and milestones for Video.js v10 rebuild and the future of v8
+- [Browser Support](./concepts/browser-support.md): Which browsers Video.js 10 supports and how it handles newer platform features
+
+## Concepts
+
+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.
+- [UI components](./concepts/ui-components.md): How Video.js UI components work — one element per component, data attributes for state, and compound composition.
+- [Accessibility](./concepts/accessibility.md): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player
+
+## How to
+
+Task-oriented guides with step-by-step instructions to achieve a specific outcome by applying one or more concepts. Each guide may assume you already understand the relevant concepts.
+
+- [Customize skins](./how-to/customize-skins.md): Learn how to customize Video.js v10 skins by copying and modifying them
+- [Build your own UI component](./how-to/build-your-own-component.md): Create custom player controls that read state, dispatch actions, and stay accessible.
+
+## Components
+
+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
+- [Time](./reference/time.md): Time display components for showing current time, duration, and remaining time in a video player
+- [TimeSlider](./reference/time-slider.md): A slider component for seeking through media playback time
+- [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 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
+
+- [renderElement](./reference/render-element.md): Utility for rendering UI component elements with state-driven props and render prop support
+- [useButton](./reference/use-button.md): Hook for creating accessible button components with keyboard and pointer interaction
+- [useContainerAttach](./reference/use-container-attach.md): Hook to register a custom container element with the player context
+- [useMediaAttach](./reference/use-media-attach.md): Hook to register a custom media element with the player context
+- [usePlayerContext](./reference/use-player-context.md): Hook to access the full player context including store, media element, and media setter
+- [useSelector](./reference/use-selector.md): Low-level hook for subscribing to derived state with customizable equality checks
+- [useSnapshot](./reference/use-snapshot.md): Hook to subscribe to a State container's current value
+
+## Features
+
+API reference for feature modules that provide player capabilities and state.
+
+- [createSelector](./reference/create-selector.md): Create a type-safe selector for a store slice's state
+- [Buffer](./reference/feature-buffer.md): Buffered and seekable time range state for the player store
+- [Controls](./reference/feature-controls.md): User activity and controls visibility state for the player store
+- [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
+- [Text tracks](./reference/feature-text-tracks.md): Subtitles, captions, and chapter track state for the player store
+- [Time](./reference/feature-time.md): Playback position and duration state for the player store
+- [Volume](./reference/feature-volume.md): Volume level and mute 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.