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

package/docs/reference/playback-rate-button.md

@@ -14,6 +14,8 @@ tsx
 
 Cycles through playback rates on click. The default rate list is `[0.2, 0.5, 0.7, 1, 1.2, 1.5, 1.7, 2]`. After the last rate, it wraps back to the first. If the current rate isn’t in the list (e.g., set programmatically), the button jumps to the next rate greater than the current one.
 
+When `menuTrigger` is enabled, activation opens the linked playback-rate menu instead of cycling through rates. Use this mode when the button is the trigger for a `Menu` that contains playback-rate options.
+
 ## Styling
 
 Display the current rate using the `data-rate` attribute:
@@ -32,6 +34,8 @@ tsx
 
 Renders a `<button>` with an automatic `aria-label` of `"Playback rate {rate}"` (e.g., `"Playback rate 1.5"`). 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
@@ -132,6 +136,18 @@ Type
 
 `string | ((state: PlaybackRateButtonState) => string)`
 
+`menuTrigger`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+When true, pointer activation opens a menu instead of cycling. React sets this automatically inside `Menu.Trigger`.
+
 ### State
 
 State is accessible via the `render`, `className`, and `style` props.

package/docs/reference/player-container.md

@@ -10,7 +10,9 @@ tsx
 <Player.Provider>
   <Player.Container>
     <video src="video.mp4" />
-    <Controls />
+    <Controls.Root>
+      {/* ... */}
+    </Controls.Root>
   </Player.Container>
 </Player.Provider>
 ```
@@ -41,7 +43,9 @@ tsx
 ```
 <Player.Container style={{ width: 640, aspectRatio: '16/9' }}>
   <video src="video.mp4" />
-  <Controls />
+  <Controls.Root>
+    {/* ... */}
+  </Controls.Root>
 </Player.Container>
 ```
 
@@ -92,7 +96,9 @@ tsx
 <Player.Provider>
   <Player.Container>
     <video src="video.mp4" />
-    <Controls />          {/* fullscreen, activity detection, gestures */}
+    <Controls.Root>          {/* fullscreen, activity detection, gestures */}
+      {/* ... */}
+    </Controls.Root>
   </Player.Container>
 
   <Transcript />          {/* state & actions, but no container behaviors */}

package/docs/reference/player-provider.md

@@ -93,7 +93,9 @@ tsx
 <Player.Provider>
   <Player.Container>
     <video src="video.mp4" />
-    <Controls />          {/* goes fullscreen with the video */}
+    <Controls.Root>          {/* goes fullscreen with the video */}
+      {/* ... */}
+    </Controls.Root>
   </Player.Container>
 
   <Transcript />          {/* outside container — still has store access */}

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

@@ -0,0 +1,59 @@
+# 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
+
+```
+const quality = useQualityOptions();
+
+<Menu.RadioGroup value={quality.value} onValueChange={quality.setValue}>
+  <Menu.GroupLabel>Quality</Menu.GroupLabel>
+  {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>
+```
+
+## 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` 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. It receives an accessible label from the `label` prop or defaults to `Quality`.

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

@@ -0,0 +1,93 @@
+# 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
+
+### Host Properties
+
+Property
+
+Type
+
+Default
+
+Details
+
+`engine`
+
+`Composition<SimpleHlsAudioOnlyEngineState, SimpleHlsAudioOnlyEngineContext>`
+
+`—`
+
+▸
+
+Description
+
+Read-only. Underlying playback engine — the low-level SPF reactive composition that drives playback. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods.
+
+`preload`
+
+`'' | 'none' | 'metadata' | 'auto'`
+
+`''`
+
+▸
+
+Description
+
+Preload type (`'none'` / `'metadata'` / `'auto'`).
+
+`src`
+
+`string`
+
+`''`
+
+### Attributes
+
+Renders a native `<audio>` element and accepts these media attributes as React props. The standard ones behave as described in the [MDN media attributes reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio): `autopictureinpicture``autoPlay``controls``controlslist``crossOrigin``disablepictureinpicture``disableremoteplayback``loading``loop``muted``playsInline``poster``preload``src``stream-type`
+
+### Events
+
+Handle these media events with React event props (e.g. `onPlay`, `onTimeUpdate`). See [media events](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement#events): `abort``canplay``canplaythrough``durationchange``emptied``ended``error``loadeddata``loadedmetadata``loadstart``pause``play``playing``progress``ratechange``seeked``seeking``stalled``suspend``timeupdate``volumechange``waiting`
+
+These media events have no React prop — attach a listener through a `ref` with `addEventListener`: `addtrack``change``removetrack`
+
+This element dispatches no events beyond the media events above.
+
+### Methods
+
+Supports these methods from the native media API. See [HTMLMediaElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) for the core methods: `addTextTrack``canPlayType``load``pause``play`
+
+In React, call these through a `ref` to the element.

package/docs/reference/simple-hls-video.md

@@ -0,0 +1,150 @@
+# 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
+
+### Host Properties
+
+Property
+
+Type
+
+Default
+
+Details
+
+`engine`
+
+`Composition<SimpleHlsEngineState, SimpleHlsEngineContext>`
+
+`—`
+
+▸
+
+Description
+
+Read-only. Underlying playback engine — the low-level SPF reactive composition that drives playback. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods.
+
+`preload`
+
+`'' | 'none' | 'metadata' | 'auto'`
+
+`''`
+
+▸
+
+Description
+
+Preload type (`'none'` / `'metadata'` / `'auto'`).
+
+`src`
+
+`string`
+
+`''`
+
+### Attributes
+
+Renders a native `<video>` element and accepts these media attributes as React props. The standard ones behave as described in the [MDN media attributes reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video): `autopictureinpicture``autoPlay``controls``controlslist``crossOrigin``disablepictureinpicture``disableremoteplayback``loading``loop``muted``playsInline``poster``preload``src``stream-type`
+
+### Events
+
+Handle these media events with React event props (e.g. `onPlay`, `onTimeUpdate`). See [media events](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement#events): `abort``canplay``canplaythrough``durationchange``emptied``ended``error``loadeddata``loadedmetadata``loadstart``pause``play``playing``progress``ratechange``resize``seeked``seeking``stalled``suspend``timeupdate``volumechange``waiting`
+
+These media events have no React prop — attach a listener through a `ref` with `addEventListener`: `addtrack``change``enterpictureinpicture``leavepictureinpicture``removetrack`
+
+This element dispatches no events beyond the media events above.
+
+### Methods
+
+Supports these methods from the native media API. See [HTMLMediaElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) for the core methods: `addTextTrack``canPlayType``exitFullscreen``exitPictureInPicture``load``pause``play``requestFullscreen``requestPictureInPicture`
+
+In React, call these through a `ref` to the element.
+
+### CSS Custom Properties
+
+Variable
+
+Details
+
+`--media-video-border-radius`
+
+▸
+
+Description
+
+Border radius of the video element.
+
+`--media-object-fit`
+
+▸
+
+Description
+
+Object fit for the video.
+
+`--media-object-position`
+
+▸
+
+Description
+
+Object position for the video.
+
+`--media-caption-track-duration`
+
+▸
+
+Description
+
+Duration of the caption track transition.
+
+`--media-caption-track-delay`
+
+▸
+
+Description
+
+Delay before the caption track transition.
+
+`--media-caption-track-y`
+
+▸
+
+Description
+
+Vertical offset of the caption track.

package/docs/reference/time-slider.md

@@ -282,6 +282,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
@@ -382,6 +394,18 @@ Description
 
 Symbol prepended to remaining time.
 
+`toggle`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+Whether the time display can be toggled.
+
 `type`
 
 `'current' | 'duration' | 'remaining'`

package/docs/reference/tooltip.md

@@ -87,7 +87,7 @@ export default function BasicUsage() {
         <Tooltip.Trigger className="trigger">Hover me</Tooltip.Trigger>
         <Tooltip.Popup className="media-tooltip">
           <Tooltip.Arrow className="arrow" />
-          Tooltip content
+          <Tooltip.Label>Tooltip content</Tooltip.Label>
         </Tooltip.Popup>
       </Tooltip.Root>
     </div>
@@ -152,21 +152,21 @@ export default function Grouping() {
           <Tooltip.Trigger className="trigger">Play</Tooltip.Trigger>
           <Tooltip.Popup className="media-tooltip">
             <Tooltip.Arrow className="arrow" />
-            Play video
+            <Tooltip.Label>Play video</Tooltip.Label>
           </Tooltip.Popup>
         </Tooltip.Root>
         <Tooltip.Root>
           <Tooltip.Trigger className="trigger">Mute</Tooltip.Trigger>
           <Tooltip.Popup className="media-tooltip">
             <Tooltip.Arrow className="arrow" />
-            Mute audio
+            <Tooltip.Label>Mute audio</Tooltip.Label>
           </Tooltip.Popup>
         </Tooltip.Root>
         <Tooltip.Root>
           <Tooltip.Trigger className="trigger">Fullscreen</Tooltip.Trigger>
           <Tooltip.Popup className="media-tooltip">
             <Tooltip.Arrow className="arrow" />
-            Enter fullscreen
+            <Tooltip.Label>Enter fullscreen</Tooltip.Label>
           </Tooltip.Popup>
         </Tooltip.Root>
       </Tooltip.Provider>
@@ -628,4 +628,88 @@ Indicates how the tooltip is aligned relative to the specified side.
 
 Arrow
 
-Decorative arrow pointing from the tooltip toward the trigger. Hidden from assistive technology.
+Decorative arrow pointing from the tooltip toward the trigger. Hidden from assistive technology.
+
+### 
+
+Label
+
+Tooltip body label; defaults to context `content.label` from the linked trigger.
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-open`
+
+▸
+
+Description
+
+Present when the tooltip is open.
+
+`data-side`
+
+`'top' | 'bottom' | 'left' | 'right'`
+
+▸
+
+Description
+
+Indicates which side the tooltip is positioned relative to the trigger.
+
+`data-align`
+
+`'start' | 'center' | 'end'`
+
+▸
+
+Description
+
+Indicates how the tooltip is aligned relative to the specified side.
+
+### 
+
+Shortcut
+
+Keyboard shortcut hint; apply skin `className` (CSS: `media-tooltip__kbd`; Tailwind: `popup.tooltipShortcut`).
+
+#### Data attributes
+
+Attribute
+
+Type
+
+Details
+
+`data-open`
+
+▸
+
+Description
+
+Present when the tooltip is open.
+
+`data-side`
+
+`'top' | 'bottom' | 'left' | 'right'`
+
+▸
+
+Description
+
+Indicates which side the tooltip is positioned relative to the trigger.
+
+`data-align`
+
+`'start' | 'center' | 'end'`
+
+▸
+
+Description
+
+Indicates how the tooltip is aligned relative to the specified side.

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

@@ -2,7 +2,7 @@
 
 Hook to register a custom media element with the player context
 
-`useMediaAttach` returns a setter function for attaching a media element to the player context. The built-in `<Video>` and `<Audio>` components use this internally — you only need it when building a custom media element.
+`useMediaAttach` returns a setter function for attaching a media element to the player context. The built-in `<Video>` and `<Audio>` components use this internally – you only need it when building a custom media element.
 
 CustomMedia.tsx
 
@@ -27,7 +27,7 @@ For standard `<video>` and `<audio>` playback, use the built-in components.
 
 ## Safe outside Provider
 
-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 a Player `Provider`. 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,109 @@
 # Player.useMedia
 
-Hook to access the underlying media element from within a Player.Provider
+Hook to access the media object from within a Player.Provider
 
-`Player.useMedia` returns the current `HTMLMediaElement` (or `null` if no media element has been registered yet). Use it to interact directly with the native media element when needed. It must be called within a `Player.Provider`. The media element becomes available after a `<Video>` or `<Audio>` component mounts inside the provider tree. Also available as a standalone import (`import { useMedia } from '@videojs/react'`) — identical behavior, no typing difference. To attach a custom media element instead of the built-in components, see [`useMediaAttach`](./use-media-attach.md).
+`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).
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer, isMediaSourceCapable, isMediaVideoDimensionsCapable } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const Player = createPlayer({
+  features: videoFeatures,
+});
+
+function MediaInfo() {
+  const media = Player.useMedia();
+
+  if (!media) return null;
+
+  return (
+    <dl className="info-panel">
+      {isMediaSourceCapable(media) && (
+        <div>
+          <dt>src</dt>
+          <dd>{media.currentSrc || '—'}</dd>
+        </div>
+      )}
+      {isMediaVideoDimensionsCapable(media) && (
+        <>
+          <div>
+            <dt>videoWidth</dt>
+            <dd>{media.videoWidth}px</dd>
+          </div>
+          <div>
+            <dt>videoHeight</dt>
+            <dd>{media.videoHeight}px</dd>
+          </div>
+        </>
+      )}
+    </dl>
+  );
+}
+
+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
+        />
+        <MediaInfo />
+      </Player.Container>
+    </Player.Provider>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.info-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 12px;
+  margin: 0;
+  font-size: 0.8125rem;
+  background: rgba(0, 0, 0, 0.05);
+  border-top: 1px solid rgba(0, 0, 0, 0.1);
+}
+
+.info-panel div {
+  display: flex;
+  gap: 8px;
+}
+
+.info-panel dt {
+  min-width: 80px;
+  color: #6b7280;
+}
+
+.info-panel dd {
+  margin: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+```
 
 ## API Reference