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

package/docs/reference/quality-radio-group.md

@@ -0,0 +1,208 @@
+# QualityRadioGroup
+
+A menu radio group for selecting video quality
+
+Creates radio items from the player video rendition state and selects automatic or manual quality.
+
+## Anatomy
+
+tsx
+
+```
+<Menu.RadioGroup>
+  <Menu.GroupLabel />
+  <Menu.RadioItem>
+    <Menu.ItemIndicator />
+  </Menu.RadioItem>
+</Menu.RadioGroup>
+```
+
+## Behavior
+
+The group is available when the configured media exposes more than one video rendition. The first generated option is `Auto`; selecting it returns control to adaptive bitrate selection. Pass `formatRendition` to customize visible rendition labels.
+
+[`useQualityOptions`](./use-quality-options.md) returns `null` when the [quality feature](./feature-quality.md) is not configured. Use the returned options with [`Menu.RadioGroup`](./menu.md).
+
+## Styling
+
+Attribute
+
+Values
+
+Description
+
+`data-quality`
+
+`string`
+
+Current quality value.
+
+`data-disabled`
+
+Present / absent
+
+Present when quality selection is disabled.
+
+`data-availability`
+
+`"available"` / `"unavailable"`
+
+Whether multiple renditions are available.
+
+## Accessibility
+
+The group uses the menu radio group pattern.
+
+Give `Menu.RadioGroup` an accessible name with `aria-label` or a nested `Menu.GroupLabel`.
+
+## Examples
+
+### Basic usage
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer, Menu, useQualityOptions } from '@videojs/react';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+import { videoFeatures } from '@videojs/react/video';
+import type { ReactNode } from 'react';
+
+const Player = createPlayer({ features: videoFeatures });
+const src = 'https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4.m3u8';
+
+function QualityMenu(): ReactNode {
+  const quality = useQualityOptions();
+  if (quality?.state.availability !== 'available') return null;
+
+  return (
+    <Menu.Root side="top" align="end">
+      <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
+        Quality
+      </Menu.Trigger>
+      <Menu.Content className="menu">
+        <Menu.RadioGroup
+          className="menu-group"
+          value={quality.value}
+          onValueChange={quality.setValue}
+          aria-label="Quality"
+        >
+          {quality.options.map((option) => (
+            <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled} className="menu-item">
+              <span>
+                {option.label}
+                {option.tier ? <sup className="menu-tier">{option.tier}</sup> : null}
+              </span>
+              {option.badge ? <span className="menu-badge">{option.badge}</span> : null}
+              <Menu.ItemIndicator checked={option.value === quality.value} forceMount className="menu-indicator">
+                ✓
+              </Menu.ItemIndicator>
+            </Menu.RadioItem>
+          ))}
+        </Menu.RadioGroup>
+      </Menu.Content>
+    </Menu.Root>
+  );
+}
+
+export default function BasicUsage() {
+  return (
+    <Player.Provider>
+      <Player.Container className="media-container">
+        <HlsJsVideo src={src} autoPlay crossOrigin="anonymous" muted playsInline loop />
+        <div className="menu-bar">
+          <QualityMenu />
+        </div>
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.menu-bar {
+  position: absolute;
+  right: 10px;
+  bottom: 10px;
+}
+
+.settings-trigger {
+  padding: 6px 16px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.35);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.menu {
+  --media-menu-side-offset: 8px;
+  box-sizing: border-box;
+  display: grid;
+  gap: 2px;
+  min-width: 180px;
+  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
+  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
+  padding: 6px;
+  margin: 0;
+  overflow: auto;
+  overscroll-behavior: none;
+  font-size: 14px;
+  color: white;
+  background: rgba(0, 0, 0, 0.88);
+  border: 0;
+  border-radius: 8px;
+  backdrop-filter: blur(10px);
+}
+
+.menu-group {
+  display: grid;
+  gap: 2px;
+}
+
+.menu-item {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  justify-content: space-between;
+  min-height: 32px;
+  padding: 0 10px;
+  font: inherit;
+  color: inherit;
+  cursor: pointer;
+  background: none;
+  border: 0;
+  border-radius: 6px;
+}
+
+.menu-item[data-highlighted] {
+  background: rgba(255, 255, 255, 0.16);
+}
+
+.menu-tier {
+  margin-left: 2px;
+  font-size: 10px;
+}
+
+.menu-badge {
+  margin-left: auto;
+  color: rgba(255, 255, 255, 0.72);
+}
+
+.menu-indicator {
+  opacity: 0;
+}
+
+[role="menuitemradio"][aria-checked="true"] .menu-indicator {
+  opacity: 1;
+}
+```

package/docs/reference/register-i18n.md

@@ -0,0 +1,64 @@
+# registerI18n
+
+Register or merge translation strings for a BCP 47 locale tag in the global i18n registry
+
+`registerI18n` merges a partial translation map into the process-wide registry for a locale tag. Components carry their own English fallback text. Built-in non-English packs lazy-load automatically; call `registerI18n` for custom locales, CDN locale modules, or patched shipped packs before the provider renders.
+
+Keys are nested semantic names such as `buttons.play` and `buttons.pause`. See [Translation keys](./translation-phrases.md) for the complete catalog.
+
+ts
+
+```
+import { registerI18n } from '@videojs/react/i18n';
+
+registerI18n('es', {
+  buttons: {
+    play: 'Reproducir',
+    pause: 'Pausar',
+  },
+});
+```
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`locale*`
+
+`string & object | 'ar' | 'az' | 'bs' ...`
+
+`—`
+
+▸
+
+Description
+
+BCP 47 tag (normalized to lowercase; unicode extensions stripped for the registry key).
+
+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' | 'it' | 'ja' | 'ko' | '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'`
+
+`translations*`
+
+`Partial<Translations>`
+
+`—`
+
+▸
+
+Description
+
+Partial nested locale values; merges with any existing layer for the tag.
+
+### Return Value
+
+`void`

package/docs/reference/seek-button.md

@@ -38,13 +38,7 @@ 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
-        />
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <div className="buttons">
           <SeekButton
             seconds={-5}
@@ -126,7 +120,7 @@ Whether the button is disabled.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
 `''`
 
@@ -138,7 +132,7 @@ Custom label for the button.
 
 Type
 
-`string | ((state: SeekButtonState) => string)`
+`Text | string | ((state: SeekButtonState) => string | Text)`
 
 `seconds`
 
@@ -184,7 +178,7 @@ Whether the button seeks forward or backward.
 
 `label`
 
-`string`
+`Text | string`
 
 ### Data attributes
 

package/docs/reference/simple-hls-audio-only.md

@@ -0,0 +1,41 @@
+# SimpleHlsAudioOnly
+
+Audio-only HLS element that plays the audio rendition of an HLS stream
+
+Audio-only HLS element that plays just the audio rendition of an HLS stream — even when the source is a mixed audio/video manifest. Useful for audio podcast players, background audio, and bandwidth-constrained contexts where downloading video data would be wasted. For full audio/video HLS playback, see [SimpleHlsVideo](/docs/framework/html/reference/simple-hls-video/).
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { SimpleHlsAudioOnly } from '@videojs/react/media/simple-hls-audio-only';
+
+export default function BasicUsage() {
+  return <SimpleHlsAudioOnly className="simple-hls-audio-only" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" controls />;
+}
+```
+```
+.simple-hls-audio-only {
+  width: 100%;
+  height: 54px;
+}
+```
+
+## API Reference
+
+### Props
+
+Accepts the standard React props for a native `<audio>`.
+
+### 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/simple-hls-video.md

@@ -0,0 +1,41 @@
+# SimpleHlsVideo
+
+Lightweight HLS video element with minimal bundle size
+
+Lightweight HLS video element optimized for minimal bundle size. For full hls.js feature support, use [HlsJsVideo](/docs/framework/html/reference/hlsjs-video/) instead.
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { SimpleHlsVideo } from '@videojs/react/media/simple-hls-video';
+
+export default function BasicUsage() {
+  return <SimpleHlsVideo className="simple-hls-video" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoPlay muted playsInline loop />;
+}
+```
+```
+.simple-hls-video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+```
+
+## API Reference
+
+### Props
+
+Accepts the standard React props for a native `<video>`.
+
+### 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/slider.md

@@ -301,7 +301,7 @@ Whether the slider is non-interactive.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
 `''`
 
@@ -313,7 +313,7 @@ Custom label for the slider.
 
 Type
 
-`string | ((state: SliderState) => string)`
+`Text | string | ((state: SliderState) => string | Text)`
 
 `largeStep`
 

package/docs/reference/thumbnail.md

@@ -305,7 +305,7 @@ The thumbnail image failed to load.
 
 Description
 
-No thumbnail is available and not loading — the component should be hidden.
+Whether the component is hidden because no thumbnail is available and it is not loading.
 
 ### Data attributes
 

package/docs/reference/time-slider.md

@@ -42,7 +42,7 @@ css
 
 ## Accessibility
 
-Renders with `role="slider"` and automatic `aria-label` of “Seek”. Override with the `label` prop. Keyboard controls:
+Renders with `role="slider"` and an automatic `aria-label` that resolves to “Seek” from the active locale. Override with the `label` prop. Keyboard controls:
 
 *   Arrow Left / Arrow Right: step by `step` increment
 *   Page Up / Page Down: step by `largeStep` increment
@@ -69,13 +69,7 @@ export default function WithParts() {
   return (
     <Player.Provider>
       <Player.Container className="media-container">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <TimeSlider.Root className="media-time-slider">
           <TimeSlider.Track className="media-slider-track">
             <TimeSlider.Buffer className="media-slider-buffer" />
@@ -232,9 +226,9 @@ Whether the slider is non-interactive.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
-`'Seek'`
+`''`
 
 ▸
 
@@ -244,7 +238,7 @@ Custom label for the slider.
 
 Type
 
-`string | ((state: SliderState) => string)`
+`Text | string | ((state: SliderState) => string | Text)`
 
 `largeStep`
 
@@ -282,6 +276,18 @@ Description
 
 Axis of slider movement.
 
+`pauseOnDrag`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+When true, pause playback while the user is dragging the thumb, resuming on release if it was playing before.
+
 `step`
 
 `number`

package/docs/reference/time.md

@@ -24,6 +24,16 @@ Three display types — `current`, `duration`, and `remaining` — in digital fo
 
 Hour display is triggered when either the current value or the duration exceeds 1 hour, ensuring consistency within a Group. Remaining time displays a negative sign (customizable via the `negativeSign` prop).
 
+Use `toggle` to let current displays switch between elapsed and remaining time, or remaining and duration displays switch between those two values. The initial display comes from `type`.
+
+tsx
+
+```
+<Time.Value toggle />
+<Time.Value toggle type="remaining" />
+<Time.Value toggle type="duration" />
+```
+
 ## Styling
 
 The negative sign is rendered inside `<span aria-hidden="true">` and can be hidden with CSS:
@@ -45,6 +55,8 @@ Each `<Time.Value>` has:
 
 No `aria-live` region is used — time updates too frequently and might overwhelm screen readers. The separator is `aria-hidden="true"` since screen readers already hear each time value separately. The negative sign is also `aria-hidden` because `aria-valuetext` already conveys “remaining”. In React, `<time datetime>` provides machine-readable time for parsers.
 
+Toggleable time displays receive `role="button"` and keyboard support for Enter and Space.
+
 ## Examples
 
 ### Current Time
@@ -65,13 +77,7 @@ export default function CurrentTime() {
   return (
     <Player.Provider>
       <Player.Container className="media-container">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <Time.Value type="current" className="media-time" />
       </Player.Container>
     </Player.Provider>
@@ -120,13 +126,7 @@ export default function CurrentDuration() {
   return (
     <Player.Provider>
       <Player.Container className="media-container">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <Time.Group className="time-group">
           <Time.Value type="current" />
           <Time.Separator />
@@ -182,13 +182,7 @@ export default function Remaining() {
   return (
     <Player.Provider>
       <Player.Container className="media-container">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <Time.Value type="remaining" className="media-time" />
       </Player.Container>
     </Player.Provider>
@@ -237,13 +231,7 @@ export default function CustomSeparator() {
   return (
     <Player.Provider>
       <Player.Container className="media-container">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <Time.Group className="time-group">
           <Time.Value type="current" />
           <Time.Separator> of </Time.Separator>
@@ -299,13 +287,7 @@ export default function CustomNegativeSign() {
   return (
     <Player.Provider>
       <Player.Container className="media-container">
-        <Video
-          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
-          autoPlay
-          muted
-          playsInline
-          loop
-        />
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
         <Time.Value type="remaining" negativeSign="~" className="media-time" />
       </Player.Container>
     </Player.Provider>
@@ -356,7 +338,7 @@ Details
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
 `''`
 
@@ -368,7 +350,7 @@ Custom label for accessibility.
 
 Type
 
-`string | ((state: TimeState) => string)`
+`Text | string | ((state: TimeState) => string | Text)`
 
 `negativeSign`
 
@@ -382,6 +364,18 @@ Description
 
 Symbol prepended to remaining time.
 
+`toggle`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Whether the time display can be toggled.
+
 `type`
 
 `'current' | 'duration' | 'remaining'`