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

package/docs/reference/use-locale.md

@@ -0,0 +1,124 @@
+# useLocale
+
+React hook that returns the active BCP 47 locale from the nearest I18nProvider
+
+`useLocale` returns the resolved BCP 47 tag from the nearest [`I18nProvider`](./i18n-provider.md), or `'en'` when none is mounted.
+
+Use it when UI copy depends on the active locale outside the translator, for example formatting or caption language hooks.
+
+## Example
+
+Switch the provider locale to see `useLocale` supply the BCP 47 tag used to format a date.
+
+Localeen-USfr-FRja-JP
+
+Active locale
+
+en-US
+
+Formatted date
+
+January 15, 2026
+
+App.tsx
+
+App.css
+
+```
+import { I18nProvider, useLocale } from '@videojs/react/i18n';
+import { useState } from 'react';
+
+import './BasicUsage.css';
+
+const locales = ['en-US', 'fr-FR', 'ja-JP'] as const;
+type Locale = (typeof locales)[number];
+
+function LocaleDetails() {
+  const locale = useLocale();
+  const date = new Intl.DateTimeFormat(locale, {
+    dateStyle: 'long',
+    timeZone: 'UTC',
+  }).format(new Date('2026-01-15T12:00:00Z'));
+
+  return (
+    <dl className="react-use-locale-basic__output">
+      <div>
+        <dt>Active locale</dt>
+        <dd>{locale}</dd>
+      </div>
+      <div>
+        <dt>Formatted date</dt>
+        <dd lang={locale}>{date}</dd>
+      </div>
+    </dl>
+  );
+}
+
+export default function BasicUsage() {
+  const [locale, setLocale] = useState<Locale>('en-US');
+
+  return (
+    <div className="react-use-locale-basic">
+      <label>
+        Locale
+        <select value={locale} onChange={(event) => setLocale(event.currentTarget.value as Locale)}>
+          {locales.map((value) => (
+            <option key={value}>{value}</option>
+          ))}
+        </select>
+      </label>
+      <I18nProvider locale={locale}>
+        <LocaleDetails />
+      </I18nProvider>
+    </div>
+  );
+}
+```
+```
+.react-use-locale-basic {
+  display: grid;
+  gap: 16px;
+  padding: 16px;
+}
+
+.react-use-locale-basic label,
+.react-use-locale-basic__output div {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.react-use-locale-basic select {
+  padding: 4px 8px;
+}
+
+.react-use-locale-basic__output {
+  display: grid;
+  gap: 8px;
+  margin: 0;
+}
+
+.react-use-locale-basic__output dt {
+  color: #6b7280;
+}
+
+.react-use-locale-basic__output dd {
+  margin: 0;
+}
+```
+
+## API Reference
+
+### Return Value
+
+Type
+
+Details
+
+`string & object | 'ar' | 'az' | 'bs' ...`
+
+▸
+
+Type
+
+`string & object | 'ar' | 'az' | 'bs' | 'bg' | 'bn' | 'ca' | 'cs' | 'cy' | 'da' | 'de' | 'el' | 'es' | 'et' | 'eu' | 'fa' | 'fi' | 'fr' | 'gd' | 'gl' | 'he' | 'hi' | 'hr' | 'hu' | 'id' | 'it' | 'ja' | 'ko' | 'lt' | 'lv' | 'mr' | 'nb' | 'nl' | 'nn' | 'ne' | 'oc' | 'pl' | 'pt-BR' | 'pt-PT' | 'ro' | 'ru' | 'sk' | 'sl' | 'sr' | 'sv' | 'te' | 'th' | 'tr' | 'uk' | 'vi' | 'zh-CN' | 'zh-TW'`

package/docs/reference/use-media-attach.md

@@ -25,9 +25,9 @@ You only need `useMediaAttach` if you’re replacing the built-in `<Video>` or `
 
 For standard `<video>` and `<audio>` playback, use the built-in components.
 
-## Safe outside Provider
+## Safe outside Player
 
-Returns `undefined` when called outside a Player `Provider`. Check the return value before using it – this avoids crashes in components that may render outside the player tree.
+Returns `undefined` when called outside `Player`. Check the return value before using it – this avoids crashes in components that may render outside the player tree.
 
 ## API Reference
 

package/docs/reference/use-media.md

@@ -1,8 +1,14 @@
-# Player.useMedia
+# useMedia
 
-Hook to access the media object from within a Player.Provider
+Hook to access the media object from within a Player
 
-`Player.useMedia` (from [`createPlayer`](./create-player.md)) returns the current `Media` object (or `null` if no media has been registered yet). `Media` is a runtime-agnostic playback interface — any instance that conforms to it, including an `HTMLVideoElement`, can be the media. It exposes capabilities like `play()` and event subscription rather than assuming a native element. It must be called within a `Player.Provider`. The media object becomes available after a `<Video>` or `<Audio>` component mounts inside the provider tree. To attach a custom media element instead of the built-in components, see [`useMediaAttach`](./use-media-attach.md).
+The `useMedia` hook returned by [`createPlayer`](./create-player.md) returns the current `Media` object (or `null` if no media has been registered yet). `Media` is a runtime-agnostic playback interface — any instance that conforms to it, including an `HTMLVideoElement`, can be the media. It exposes capabilities like `play()` and event subscription rather than assuming a native element. It must be called within the matching `Player`. The media object becomes available after a `<Video>` or `<Audio>` component mounts inside the player tree. To attach a custom media element instead of the built-in components, see [`useMediaAttach`](./use-media-attach.md).
+
+tsx
+
+```
+const { Player, useMedia } = createPlayer({ features: videoFeatures });
+```
 
 ## Examples
 
@@ -13,15 +19,15 @@ App.tsx
 App.css
 
 ```
-import { createPlayer, isMediaSourceCapable, isMediaVideoDimensionsCapable } from '@videojs/react';
+import { Container, createPlayer, isMediaSourceCapable, isMediaVideoDimensionsCapable } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({
+const { Player, useMedia } = createPlayer({
   features: videoFeatures,
 });
 
 function MediaInfo() {
-  const media = Player.useMedia();
+  const media = useMedia();
 
   if (!media) return null;
 
@@ -51,18 +57,12 @@ function MediaInfo() {
 
 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
-        />
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <MediaInfo />
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```

package/docs/reference/use-playback-rate-options.md

@@ -0,0 +1,59 @@
+# usePlaybackRateOptions
+
+Hook to build playback rate menu options from the player playback rate state
+
+`usePlaybackRateOptions` returns the current playback rate, the available options, and `setRate` / `setValue` callbacks for wiring rate selection into a menu. It returns `null` when the [playback rate feature](./feature-playback-rate.md) is not configured.
+
+SpeedMenu.tsx
+
+```
+import { Menu, usePlaybackRateOptions } from "@videojs/react";
+
+function SpeedMenu() {
+  const playbackRate = usePlaybackRateOptions();
+  if (playbackRate?.state.availability !== "available") return null;
+
+  return (
+    <Menu.RadioGroup value={playbackRate.value} onValueChange={playbackRate.setValue} aria-label="Speed">
+      {playbackRate.options.map((option) => (
+        <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled}>
+          {option.label}
+          <Menu.ItemIndicator checked={option.value === playbackRate.value} />
+        </Menu.RadioItem>
+      ))}
+    </Menu.RadioGroup>
+  );
+}
+```
+
+Options come from the player’s configured playback rates. Labels default to the rate followed by a multiplication sign (e.g. `1.5×`); pass `formatRate` to customize them. `setValue` accepts an option’s string value, while `setRate` accepts a number directly.
+
+See [PlaybackRateRadioGroup](./playback-rate-radio-group.md) for the component-level pattern, and [Menu](./menu.md) for a complete settings menu example.
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`props`
+
+`PlaybackRateOptionsProps`
+
+`—`
+
+▸
+
+Description
+
+Optional `label`, `formatRate`, and `disabled` overrides.
+
+### Return Value
+
+`PlaybackRateOptionsResult | null`

package/docs/reference/use-player-context.md

@@ -1,8 +1,8 @@
 # usePlayerContext
 
-Hook to access the full player context including store, media element, and media setter
+Hook to access the full player context value
 
-`usePlayerContext` returns the full `PlayerContextValue` object, which includes the store, the current media element, and the media setter.
+`usePlayerContext` returns the full `PlayerContextValue` object for lower-level integrations that need direct access to player context fields.
 
 DebugPanel.tsx
 
@@ -10,7 +10,7 @@ DebugPanel.tsx
 import { usePlayerContext } from "@videojs/react";
 
 function DebugPanel() {
-  const { store, media, setMedia } = usePlayerContext();
+  const { store, media, container } = usePlayerContext();
 
   return (
     <pre>
@@ -18,6 +18,7 @@ function DebugPanel() {
         {
           hasStore: !!store,
           hasMedia: !!media,
+          hasContainer: !!container,
           tagName: media?.tagName,
         },
         null,
@@ -86,8 +87,4 @@ Details
 
 Type
 
-`Dispatch<SetStateAction<HTMLElement | null>>`
-
-`popupGroup`
-
-`PopupGroup`
+`Dispatch<SetStateAction<HTMLElement | null>>`

package/docs/reference/use-player.md

@@ -1,8 +1,14 @@
-# Player.usePlayer
+# usePlayer
 
-Hook to access the player store from within a Player.Provider
+Hook to access the player store from within a Player
 
-`Player.usePlayer` (from [`createPlayer`](./create-player.md)) gives you access to the player store from any component within a `Player.Provider`. It’s typed to the features you passed to `createPlayer`, and has two overloads — without arguments for direct store access, or with a selector for reactive state subscriptions.
+The `usePlayer` hook returned by [`createPlayer`](./create-player.md) gives you access to the player store from any component within its `Player`. It’s typed to the features you passed to `createPlayer`, and has two overloads — without arguments for direct store access, or with a selector for reactive state subscriptions.
+
+tsx
+
+```
+const { Player, usePlayer } = createPlayer({ features: videoFeatures });
+```
 
 `usePlayer` is also available as a standalone import (`import { usePlayer } from '@videojs/react'`), but the standalone version returns an untyped `UnknownStore`. Pass a premade selector to recover typing:
 
@@ -19,7 +25,7 @@ usePlayer(selectPlayback); // PlaybackState | undefined
 
 ### Store Access
 
-Call `Player.usePlayer()` without arguments to get the store instance. Use this for imperative actions like play, pause, and volume changes. The component does not re-render on state changes.
+Call `usePlayer()` without arguments to get the store instance. Use this for imperative actions like play, pause, and volume changes. The component does not re-render on state changes.
 
 PlayPause
 
@@ -28,15 +34,15 @@ App.tsx
 App.css
 
 ```
-import { createPlayer } from '@videojs/react';
+import { Container, createPlayer } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({
+const { Player, usePlayer } = createPlayer({
   features: videoFeatures,
 });
 
 function Controls() {
-  const store = Player.usePlayer();
+  const store = usePlayer();
 
   return (
     <div className="controls">
@@ -52,18 +58,12 @@ function Controls() {
 
 export default function StoreAccess() {
   return (
-    <Player.Provider>
-      <Player.Container className="media-container">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <Controls />
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```
@@ -111,15 +111,15 @@ App.tsx
 App.css
 
 ```
-import { createPlayer } from '@videojs/react';
+import { Container, createPlayer } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({
+const { Player, usePlayer } = createPlayer({
   features: videoFeatures,
 });
 
 function StateDisplay() {
-  const state = Player.usePlayer((s) => ({
+  const state = usePlayer((s) => ({
     paused: s.paused,
     currentTime: s.currentTime,
     duration: s.duration,
@@ -143,18 +143,12 @@ function StateDisplay() {
 
 export default function Selector() {
   return (
-    <Player.Provider>
-      <Player.Container className="media-container">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <StateDisplay />
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```
@@ -196,7 +190,7 @@ export default function Selector() {
 
 ### Without Selector
 
-Access the player store from within a Player Provider.
+Access the player store from within a Player.
 
 This standalone hook has no knowledge of your configured features, so it returns an untyped `UnknownStore` whose state properties are typed as `unknown`. For typed access, use the `usePlayer` returned by `createPlayer()`, or pass a premade selector to recover the type from its return value.
 

package/docs/reference/use-quality-options.md

@@ -0,0 +1,59 @@
+# useQualityOptions
+
+Hook to build video quality menu options from the player rendition state
+
+`useQualityOptions` returns the current quality value, the available options, and a `setValue` callback for wiring quality selection into a menu. It returns `null` when the [quality feature](./feature-quality.md) is not configured.
+
+QualityMenu.tsx
+
+```
+import { Menu, useQualityOptions } from "@videojs/react";
+
+function QualityMenu() {
+  const quality = useQualityOptions();
+  if (quality?.state.availability !== "available") return null;
+
+  return (
+    <Menu.RadioGroup value={quality.value} onValueChange={quality.setValue} aria-label="Quality">
+      {quality.options.map((option) => (
+        <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled}>
+          {option.label}
+          <Menu.ItemIndicator checked={option.value === quality.value} />
+        </Menu.RadioItem>
+      ))}
+    </Menu.RadioGroup>
+  );
+}
+```
+
+The first option is always `Auto`; selecting it returns control to adaptive bitrate selection. Options carry optional `tier` and `badge` fields (e.g. `4K`, `HD`) for richer labels. Pass `formatRendition` to customize the visible rendition labels.
+
+See [QualityRadioGroup](./quality-radio-group.md) for the component-level pattern, and [Menu](./menu.md) for a complete settings menu example.
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`props`
+
+`QualityOptionsProps`
+
+`—`
+
+▸
+
+Description
+
+Optional `label`, `formatRendition`, and `disabled` overrides.
+
+### Return Value
+
+`QualityOptionsResult | null`

package/docs/reference/use-store.md

@@ -2,7 +2,7 @@
 
 Hook to access store state and actions with optional selector-based subscriptions
 
-`useStore` subscribes to a store instance directly. It has the same two overloads as [`usePlayer`](./use-player.md) — without a selector for store access, or with a selector for reactive state. Within a player provider, `usePlayer` is usually simpler since it reads the store from context. Reach for `useStore` when you have a store instance directly or need to derive computed values from the store.
+`useStore` subscribes to a store instance directly. It has the same two overloads as [`usePlayer`](./use-player.md) — without a selector for store access, or with a selector for reactive state. Within `Player`, `usePlayer` is usually simpler since it reads the store from context. Reach for `useStore` when you have a store instance directly or need to derive computed values from the store.
 
 ## Examples
 
@@ -17,15 +17,15 @@ App.tsx
 App.css
 
 ```
-import { createPlayer, useStore } from '@videojs/react';
+import { Container, createPlayer, useStore } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({
+const { Player, usePlayer } = createPlayer({
   features: videoFeatures,
 });
 
 function SeekControls() {
-  const store = Player.usePlayer();
+  const store = usePlayer();
   const s = useStore(store);
 
   return (
@@ -42,18 +42,12 @@ function SeekControls() {
 
 export default function StoreAccess() {
   return (
-    <Player.Provider>
-      <Player.Container className="media-container">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <SeekControls />
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```
@@ -101,15 +95,15 @@ App.tsx
 App.css
 
 ```
-import { createPlayer, useStore } from '@videojs/react';
+import { Container, createPlayer, useStore } from '@videojs/react';
 import { Video, videoFeatures } from '@videojs/react/video';
 
-const Player = createPlayer({
+const { Player, usePlayer } = createPlayer({
   features: videoFeatures,
 });
 
 function DerivedState() {
-  const store = Player.usePlayer();
+  const store = usePlayer();
   const derived = useStore(store, (s) => ({
     remaining: s.duration - s.currentTime,
     progress: s.duration > 0 ? (s.currentTime / s.duration) * 100 : 0,
@@ -131,18 +125,12 @@ function DerivedState() {
 
 export default function Selector() {
   return (
-    <Player.Provider>
-      <Player.Container className="media-container">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <DerivedState />
-      </Player.Container>
-    </Player.Provider>
+      </Container>
+    </Player>
   );
 }
 ```

package/docs/reference/use-translator.md

@@ -0,0 +1,119 @@
+# useTranslator
+
+React hook that returns the typed translator for the nearest I18nProvider
+
+`useTranslator` returns the translator from the nearest [`I18nProvider`](./i18n-provider.md). Control components pass text descriptors from core `getLabel()`. Custom UI can pass an opaque key with its English fallback.
+
+When no provider is mounted, the hook falls back to English registry strings so standalone demos do not throw.
+
+## Example
+
+Switch the provider locale to see `useTranslator` resolve a simple key and a parameterized key from the nearest provider.
+
+LanguageSpanishFrench
+
+Button
+
+Reproducir
+
+Parameterized
+
+Adelantar 10 segundos
+
+App.tsx
+
+App.css
+
+```
+import { I18nProvider, useTranslator } from '@videojs/react/i18n';
+import { useState } from 'react';
+
+import './BasicUsage.css';
+
+const translations = {
+  es: {
+    buttons: { play: 'Reproducir' },
+    seek: { forward: 'Adelantar {seconds} segundos' },
+  },
+  fr: {
+    buttons: { play: 'Lire' },
+    seek: { forward: 'Avancer de {seconds} secondes' },
+  },
+} as const;
+
+type Locale = keyof typeof translations;
+
+function Labels() {
+  const t = useTranslator();
+
+  return (
+    <dl className="react-use-translator-basic__output">
+      <div>
+        <dt>Button</dt>
+        <dd>{t('buttons.play', { default: 'Play' })}</dd>
+      </div>
+      <div>
+        <dt>Parameterized</dt>
+        <dd>{t('seek.forward', { seconds: 10, default: 'Seek forward {seconds} seconds' })}</dd>
+      </div>
+    </dl>
+  );
+}
+
+export default function BasicUsage() {
+  const [locale, setLocale] = useState<Locale>('es');
+
+  return (
+    <div className="react-use-translator-basic">
+      <label>
+        Language
+        <select value={locale} onChange={(event) => setLocale(event.currentTarget.value as Locale)}>
+          <option value="es">Spanish</option>
+          <option value="fr">French</option>
+        </select>
+      </label>
+      <I18nProvider locale={locale} translations={translations[locale]}>
+        <Labels />
+      </I18nProvider>
+    </div>
+  );
+}
+```
+```
+.react-use-translator-basic {
+  display: grid;
+  gap: 16px;
+  padding: 16px;
+}
+
+.react-use-translator-basic label,
+.react-use-translator-basic__output div {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.react-use-translator-basic select {
+  padding: 4px 8px;
+}
+
+.react-use-translator-basic__output {
+  display: grid;
+  gap: 8px;
+  margin: 0;
+}
+
+.react-use-translator-basic__output dt {
+  color: #6b7280;
+}
+
+.react-use-translator-basic__output dd {
+  margin: 0;
+}
+```
+
+## API Reference
+
+### Return Value
+
+`Translator`