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

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> \
+  --media <html5-video|html5-audio|hls|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,91 @@
+# 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.
+
+- [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.
+- [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
+- [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
+- [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
+- [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
+
+## 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
+- [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
+- [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
+- [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/buffering-indicator.md

@@ -0,0 +1,152 @@
+# BufferingIndicator
+
+Loading indicator that displays when the video player is buffering or waiting for data
+
+## Anatomy
+
+tsx
+
+```
+<BufferingIndicator />
+```
+
+## Behavior
+
+Shows a loading indicator when the media is waiting to buffer and not paused, but only after a configurable `delay` (default 500ms). This delay prevents the indicator from flickering during brief stalls. The indicator hides immediately when buffering ends.
+
+## Styling
+
+Hide and show the indicator based on the `data-visible` attribute.
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { BufferingIndicator, 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
+        />
+        <BufferingIndicator
+          className="media-buffering-indicator"
+          render={(props, state) => <div {...props}>{state.visible && <div className="spinner" />}</div>}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+  display: flex;
+  width: 100%;
+  height: 100%;
+}
+
+.media-buffering-indicator {
+  position: absolute;
+  inset: 0;
+  z-index: 30;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  pointer-events: none;
+}
+
+.spinner {
+  display: none;
+  width: 48px;
+  height: 48px;
+  border: 4px solid rgba(255, 255, 255, 0.3);
+  border-top-color: white;
+  border-radius: 50%;
+  animation: buffering-spin 0.8s linear infinite;
+}
+
+.media-buffering-indicator[data-visible] .spinner {
+  display: block;
+}
+
+@keyframes buffering-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+```
+
+## API Reference
+
+### Props
+
+Prop
+
+Type
+
+Default
+
+Details
+
+`delay`
+
+`number`
+
+`500`
+
+▸
+
+Description
+
+Delay in milliseconds before the indicator becomes visible.
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`visible`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the indicator should be visible. True after the delay elapses while media is waiting and not paused.
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-visible`
+
+▸
+
+Description
+
+Present when the buffering indicator is visible (after delay).

package/docs/reference/captions-button.md

@@ -0,0 +1,200 @@
+# CaptionsButton
+
+Accessible captions toggle button with availability detection and state reflection
+
+## Anatomy
+
+tsx
+
+```
+<CaptionsButton />
+```
+
+## Behavior
+
+Toggles captions and subtitles on and off. The button checks the media’s text track list for tracks with `kind="captions"` or `kind="subtitles"` and reflects availability via `data-availability`.
+
+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.
+
+## Styling
+
+Style the button based on active state:
+
+css
+
+```
+media-captions-button[data-active] .icon-on { display: inline; }
+media-captions-button:not([data-active]) .icon-off { display: inline; }
+```
+
+Hide when no caption tracks are available:
+
+css
+
+```
+media-captions-button[data-availability="unavailable"] {
+  display: none;
+}
+```
+
+## Accessibility
+
+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.
+
+## Examples
+
+### Basic Usage
+
+Captions On
+
+App.tsx
+
+App.css
+
+```
+import { CaptionsButton, 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
+        >
+          <track kind="captions" src="/docs/demos/captions-button/captions.vtt" srcLang="en" label="English" />
+        </Video>
+        <CaptionsButton
+          className="media-captions-button"
+          render={(props, state) => (
+            <button {...props}>{state.subtitlesShowing ? 'Captions Off' : 'Captions On'}</button>
+          )}
+        />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-captions-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
+
+Details
+
+`disabled`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Whether the button is disabled.
+
+`label`
+
+`string | function`
+
+`''`
+
+▸
+
+Description
+
+Custom label for the button.
+
+Type
+
+`string | ((state: CaptionsButtonState) => string)`
+
+### State
+
+State is accessible via the `render`, `className`, and `style` props.
+
+Property
+
+Type
+
+Details
+
+`availability`
+
+`'available' | 'unavailable'`
+
+`subtitlesShowing`
+
+`boolean`
+
+▸
+
+Description
+
+Whether captions/subtitles are currently enabled.
+
+`label`
+
+`string`
+
+### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-active`
+
+▸
+
+Description
+
+Present when captions are enabled.
+
+`data-availability`
+
+`'available' | 'unavailable'`
+
+▸
+
+Description
+
+Indicates captions availability (`available` or `unavailable`).