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

package/docs/reference/pip-button.md

@@ -12,7 +12,10 @@ tsx
 
 ## Behavior
 
-Toggles picture-in-picture (PiP) mode. Detects platform support through `availability` — when PiP is `"unsupported"`, the toggle does nothing.
+Toggles picture-in-picture (PiP) mode. The button derives two state hooks from `availability`:
+
+*   **`disabled`** (`true` until PiP is available, or when the `disabled` prop is set) — sets `aria-disabled="true"` and `data-disabled`. A prop-disabled, available button stays focusable but does not activate.
+*   **`hidden`** (`true` while PiP is `"unavailable"` or `"unsupported"`) — applies the native HTML `hidden` attribute on the custom element; the React component returns `null`.
 
 ## Styling
 
@@ -27,18 +30,16 @@ css
 .pip-button[data-pip] {
   background: red;
 }
-```
-
-Consider hiding the button when unsupported:
-
-css
 
-```
-.pip-button[data-availability="unsupported"] {
-  display: none;
+/* Non-interactive (disabled prop) */
+.pip-button[data-disabled] {
+  opacity: 0.5;
+  cursor: not-allowed;
 }
 ```
 
+The button remains hidden until picture-in-picture is available. The HTML element receives the native `hidden` attribute, and the React component returns `null`. No extra CSS is required.
+
 ## Accessibility
 
 Renders a `<button>` with an automatic `aria-label`: “Enter PiP” or “Exit PiP”. Override with the `label` prop. Keyboard activation: Enter / Space.
@@ -47,8 +48,6 @@ Renders a `<button>` with an automatic `aria-label`: “Enter PiP” or “Exit
 
 ### Basic Usage
 
-Enter PiP
-
 App.tsx
 
 App.css
@@ -63,13 +62,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 />
         <PiPButton
           className="media-pip-button"
           render={(props, state) => <button {...props}>{state.pip ? 'Exit PiP' : 'Enter PiP'}</button>}
@@ -129,7 +122,7 @@ Whether the button is disabled.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
 `''`
 
@@ -141,7 +134,7 @@ Custom label for the button.
 
 Type
 
-`string | ((state: PiPButtonState) => string)`
+`Text | string | ((state: PiPButtonState) => string | Text)`
 
 ### State
 
@@ -167,6 +160,26 @@ Type
 
 `'available' | 'unavailable' | 'unsupported'`
 
+`disabled`
+
+`boolean`
+
+▸
+
+Description
+
+Non-interactive but still focusable (mirrors `aria-disabled`).
+
+`hidden`
+
+`boolean`
+
+▸
+
+Description
+
+Whether the button is hidden until picture-in-picture is available.
+
 `pip`
 
 `boolean`
@@ -179,7 +192,7 @@ Whether picture-in-picture mode is currently active.
 
 `label`
 
-`string`
+`Text | string`
 
 ### Data attributes
 
@@ -205,8 +218,24 @@ Present when picture-in-picture mode is active.
 
 Description
 
-Indicates picture-in-picture availability (`available` or `unsupported`).
+Indicates picture-in-picture availability (`available`, `unavailable`, `unsupported`).
 
 Type
 
-`'available' | 'unavailable' | 'unsupported'`
+`'available' | 'unavailable' | 'unsupported'`
+
+`data-disabled`
+
+▸
+
+Description
+
+Present when the button is non-interactive (mirrors `aria-disabled`).
+
+`data-hidden`
+
+▸
+
+Description
+
+Present when the button is hidden because picture-in-picture is not available.

package/docs/reference/play-button.md

@@ -12,7 +12,7 @@ tsx
 
 ## Behavior
 
-PlayButton is a three-state button: **play** , **pause** , and **replay** . When media reaches the end (`ended` state), clicking restarts playback from the beginning.
+PlayButton is a three-state button: **play**, **pause**, and **replay**. When media reaches the end (`ended` state), clicking restarts playback from the beginning.
 
 ## Styling
 
@@ -44,7 +44,7 @@ css
 
 ## Accessibility
 
-Renders a `<button>` element with an automatic `aria-label` that updates based on state: “Play”, “Pause”, or “Replay”. Override with the `label` prop (accepts a string or function). Keyboard activation: Enter / Space.
+Renders a `<button>` element with an automatic `aria-label` that updates based on state: “Play”, “Pause”, or “Replay”. Override with the `label` prop, which accepts a text descriptor, literal string, or function returning either. A text descriptor contains an opaque translation key and English fallback, for example `{ key: 'buttons.play', text: 'Play video' }`. Keyboard activation: Enter / Space.
 
 ## Examples
 
@@ -66,12 +66,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
-        />
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline />
         <PlayButton
           className="media-play-button"
           render={(props, state) => (
@@ -133,7 +128,7 @@ Whether the button is disabled.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
 `''`
 
@@ -145,7 +140,7 @@ Custom label for the button.
 
 Type
 
-`string | ((state: PlayButtonState) => string)`
+`Text | string | ((state: PlayButtonState) => string | Text)`
 
 ### State
 
@@ -189,7 +184,7 @@ Whether playback has started (played or seeked).
 
 `label`
 
-`string`
+`Text | string`
 
 ### Data attributes
 

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
@@ -52,13 +56,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 />
         <PlaybackRateButton
           className="media-playback-rate-button"
           render={(props, state) => <button {...props}>{Math.round(state.rate * 10) / 10}&times;</button>}
@@ -118,7 +116,7 @@ Whether the button is disabled.
 
 `label`
 
-`string | function`
+`Text | string | Text) | function`
 
 `''`
 
@@ -130,7 +128,19 @@ Custom label for the button.
 
 Type
 
-`string | ((state: PlaybackRateButtonState) => string)`
+`Text | string | ((state: PlaybackRateButtonState) => string | Text)`
+
+`menuTrigger`
+
+`boolean`
+
+`false`
+
+▸
+
+Description
+
+When true, pointer activation opens a menu instead of cycling. React sets this automatically inside `Menu.Trigger`.
 
 ### State
 
@@ -148,7 +158,7 @@ Details
 
 `label`
 
-`string`
+`Text | string`
 
 ### Data attributes
 

package/docs/reference/playback-rate-radio-group.md

@@ -0,0 +1,194 @@
+# PlaybackRateRadioGroup
+
+A menu radio group for selecting playback speed
+
+Creates radio items from the player playback rate state and selects the playback speed.
+
+## Anatomy
+
+tsx
+
+```
+<Menu.RadioGroup>
+  <Menu.GroupLabel />
+  <Menu.RadioItem>
+    <Menu.ItemIndicator />
+  </Menu.RadioItem>
+</Menu.RadioGroup>
+```
+
+## Behavior
+
+The group is available when the configured media exposes playback rates. Option labels default to the rate followed by a multiplication sign (e.g. `1.5×`); pass `formatRate` to customize them.
+
+[`usePlaybackRateOptions`](./use-playback-rate-options.md) returns `null` when the [playback rate feature](./feature-playback-rate.md) is not configured. Use the returned options with [`Menu.RadioGroup`](./menu.md).
+
+## Styling
+
+Attribute
+
+Values
+
+Description
+
+`data-rate`
+
+`number`
+
+Current playback rate.
+
+`data-disabled`
+
+Present / absent
+
+Present when playback rate selection is disabled.
+
+`data-availability`
+
+`"available"` / `"unavailable"`
+
+Whether playback rates 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
+
+Speed
+
+App.tsx
+
+App.css
+
+```
+import { createPlayer, Menu, usePlaybackRateOptions } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+import type { ReactNode } from 'react';
+
+const Player = createPlayer({ features: videoFeatures });
+
+function SpeedMenu(): ReactNode {
+  const playbackRate = usePlaybackRateOptions();
+  if (playbackRate?.state.availability !== 'available') return null;
+
+  return (
+    <Menu.Root side="top" align="end">
+      <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
+        Speed
+      </Menu.Trigger>
+      <Menu.Content className="menu">
+        <Menu.RadioGroup
+          className="menu-group"
+          value={playbackRate.value}
+          onValueChange={playbackRate.setValue}
+          aria-label="Speed"
+        >
+          {playbackRate.options.map((option) => (
+            <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled} className="menu-item">
+              {option.label}
+              <Menu.ItemIndicator checked={option.value === playbackRate.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">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
+        <div className="menu-bar">
+          <SpeedMenu />
+        </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-indicator {
+  opacity: 0;
+}
+
+[role="menuitemradio"][aria-checked="true"] .menu-indicator {
+  opacity: 1;
+}
+```

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/popover.md

@@ -22,7 +22,7 @@ Displays contextual content anchored to a trigger element. By default, opens on
 
 Set `openOnHover` to open on pointer hover instead of click. Use `delay` and `closeDelay` to control timing for hover interactions.
 
-The `side` and `align` props control popup placement relative to the trigger. The popup repositions automatically to stay within viewport bounds.
+The `side` and `align` props control the preferred popup placement relative to the trigger. When the preferred side overflows the positioning boundary, the popup uses the opposite side if it has more space.
 
 In React, the component is composed from four parts: `Root` manages state, `Trigger` toggles the popover, `Popup` contains the content, and `Arrow` renders a directional arrow.
 
@@ -38,10 +38,11 @@ css
 .popover {
   --media-popover-side-offset: 8px;
   --media-popover-align-offset: 0px;
+  --media-popover-boundary-offset: 8px;
 }
 ```
 
-Style based on open state and transition phases:
+Style based on open state, rendered side, and transition phases. `data-side` reflects the rendered side and can differ from the preferred `side` prop after collision handling:
 
 css
 
@@ -55,6 +56,12 @@ css
 .popover[data-ending-style] .popup {
   opacity: 0;
 }
+.popover[data-side="top"] {
+  transform-origin: bottom center;
+}
+.popover[data-side="bottom"] {
+  transform-origin: top center;
+}
 ```
 
 ## Accessibility
@@ -81,13 +88,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="bar">
           <Popover.Root>
             <Popover.Trigger className="trigger">Settings</Popover.Trigger>
@@ -286,7 +287,7 @@ Open the popup on pointer hover instead of click.
 
 Description
 
-Which side of the trigger the popup appears on.
+Preferred side of the trigger for the popup.
 
 #### State
 
@@ -310,6 +311,12 @@ Details
 
 `'top' | 'bottom' | 'left' | 'right'`
 
+▸
+
+Description
+
+Preferred side of the trigger for the popup.
+
 `align`
 
 `'start' | 'center' | 'end'`
@@ -362,7 +369,7 @@ Present when the popover is open.
 
 Description
 
-Indicates which side the popover is positioned relative to the trigger.
+Indicates the rendered side of the popover after collision handling.
 
 `data-align`
 
@@ -472,7 +479,7 @@ Present when the popover is open.
 
 Description
 
-Indicates which side the popover is positioned relative to the trigger.
+Indicates the rendered side of the popover after collision handling.
 
 `data-align`
 
@@ -514,7 +521,7 @@ Present when the popover is open.
 
 Description
 
-Indicates which side the popover is positioned relative to the trigger.
+Indicates the rendered side of the popover after collision handling.
 
 `data-align`
 

package/docs/reference/poster.md

@@ -58,10 +58,7 @@ export default function BasicUsage() {
       <Player.Container className="media-container">
         <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline />
 
-        <Poster
-          className="media-poster"
-          src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg"
-        />
+        <Poster className="media-poster" src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg" />
 
         <PlayButton
           className="media-play-button"