@videojs/react 10.0.0-beta.31 → 10.0.0-beta.32

package/docs/how-to/show-and-hide-controls.md

@@ -0,0 +1,174 @@
+# Automatically show and hide controls
+
+Show controls while the user is active, hide them during playback, and toggle them by touch.
+
+Show controls while the user is active, fade them out during undisturbed playback, and bring them back on interaction.
+
+Note
+
+Using a pre-built [skin](../concepts/skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](../concepts/ui-components.md).
+
+## Recommended approach
+
+Wrap your control UI in [Controls](../reference/controls.md). It reads controls visibility from player state, so the whole control bar shows and hides as one unit.
+
+Play0:00
+
+App.tsx
+
+App.css
+
+```
+import { Container, Controls, createPlayer, PlayButton, Time } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
+
+        <Controls.Root>
+          <Controls.Backdrop className="controls-backdrop" />
+          <Controls.Content className="media-controls">
+            <Controls.Group className="controls-group" aria-label="Playback controls">
+              <PlayButton
+                className="button"
+                render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
+              />
+
+              <Time.Value type="current" className="time" />
+            </Controls.Group>
+          </Controls.Content>
+        </Controls.Root>
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-controls {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: flex-end;
+  padding: 12px;
+  pointer-events: none;
+  transition: opacity 0.25s;
+}
+
+.controls-backdrop {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  background: linear-gradient(to top, rgba(0, 0, 0, 0.45), transparent 45%);
+  opacity: 1;
+  transition: opacity 0.35s;
+}
+
+.controls-backdrop:not([data-visible]),
+.media-controls:not([data-visible]) {
+  opacity: 0;
+}
+
+.controls-group {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  pointer-events: auto;
+}
+
+.time {
+  display: inline-flex;
+  gap: 4px;
+  align-items: center;
+  padding-block: 8px;
+  padding-inline: 16px;
+  font-size: 14px;
+  color: black;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.25);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+
+.button {
+  padding-block: 8px;
+  padding-inline: 16px;
+  font-size: 14px;
+  color: black;
+  cursor: pointer;
+  background: rgba(255, 255, 255, 0.75);
+  border: 1px solid rgba(255, 255, 255, 0.25);
+  border-radius: 9999px;
+  backdrop-filter: blur(10px);
+}
+```
+
+## How it works
+
+The [controls feature](../reference/feature-controls.md) tracks activity on the player container:
+
+*   `userActive` is `true` while the user interacts — pointer movement, keyboard input, or focus — and flips to `false` after two seconds of inactivity.
+*   `controlsVisible` derives from activity and playback: controls stay visible while paused or while a remote playback session is connecting or connected, regardless of idle state.
+*   `toggleControls()` flips visibility, for wiring to custom triggers.
+
+On touch devices, a tap on the media toggles the controls instead of relying on pointer movement, and mid-gesture movement doesn’t flicker visibility.
+
+The feature needs the player container for activity tracking; without a container it stays inactive and warns in development.
+
+## Availability and constraints
+
+*   Activity tracking listens on the player container, so controls placed outside it don’t keep the player “active” — put control UI inside the container.
+*   Keyboard focus counts as activity: controls stay reachable for keyboard and assistive-technology users while focus is inside them.
+*   Touch and mouse behave differently by design — mouse movement shows controls, touch requires a tap. Test both.
+*   The idle delay is fixed at two seconds.
+
+## Common variations
+
+### Always-visible controls
+
+Skip the visibility wiring: render your controls without consuming `controlsVisible`. State still tracks activity for anything else that needs it.
+
+### Custom show/hide styling
+
+Controls hide by state, so you own the transition. Style the visible and hidden states in CSS — fade, slide, or scale — driven by the component’s rendered state rather than re-implementing the idle timer.
+
+## Troubleshooting
+
+### Controls never hide
+
+The media is paused (controls intentionally stay visible), a remote playback session is active, an open menu or popover holds a controls lock, or something keeps triggering activity — for example a focused element inside the container receiving repeated events.
+
+### Controls don’t come back on touch
+
+A tap on the media toggles controls. If a custom overlay covers the media and swallows pointer events, taps never reach the container; let pointer events pass through decorative overlays.
+
+### Controls flicker on Android while tapping
+
+Use the skin gestures (`tap` with the `toggleControls` action) rather than adding your own tap handlers next to the built-in behavior; competing handlers invert each other. See [Add keyboard shortcuts and gestures](./add-keyboard-shortcuts-and-gestures.md).
+
+## Related components
+
+*   [Controls](../reference/controls.md)
+*   [Player container](../reference/player-container.md)
+
+## Related API
+
+*   [Controls feature](../reference/feature-controls.md)
+
+## Related guides
+
+*   [Add keyboard shortcuts and gestures](./add-keyboard-shortcuts-and-gestures.md)
+*   [Accessibility](../concepts/accessibility.md)

package/docs/how-to/show-captions-and-subtitles.md

@@ -0,0 +1,156 @@
+# Show captions and subtitles
+
+Show captions and subtitles, and let users turn them on and pick a language.
+
+Add captions and subtitles to media, and let users turn them on and pick a language.
+
+Note
+
+Using a pre-built [skin](../concepts/skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](../concepts/ui-components.md).
+
+## Recommended approach
+
+Add WebVTT tracks as `<track>` children of the media element, and give users a [CaptionsButton](../reference/captions-button.md) to toggle them.
+
+App.tsx
+
+App.css
+
+```
+import { CaptionsButton, Container } from '@videojs/react';
+import { Video, VideoPlayer } from '@videojs/react/video';
+
+export default function BasicUsage() {
+  return (
+    <VideoPlayer>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop>
+          <track kind="captions" src="/docs/demos/text-tracks/captions.vtt" srcLang="en" label="English" default />
+        </Video>
+        <CaptionsButton
+          className="media-captions-button"
+          render={(props, state) => (
+            <button {...props}>{state.subtitlesShowing ? 'Captions Off' : 'Captions On'}</button>
+          )}
+        />
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+}
+
+.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);
+}
+```
+
+## How it works
+
+The [text track feature](../reference/feature-text-tracks.md) mirrors the media element’s `textTracks` into player state:
+
+*   `textTrackList` holds every track with its `id`, `kind`, `label`, `language`, and `mode`.
+*   `subtitlesShowing` is `true` when any caption or subtitle track is showing.
+*   `toggleSubtitles(forceShow?)` shows or hides all caption and subtitle tracks.
+*   `selectSubtitlesTrack(id)` shows one track and disables the rest; pass `'off'` to disable all.
+
+Tracks don’t have to come from `<track>` elements: tracks that streaming media exposes (for example in-manifest HLS captions) appear in `textTrackList` the same way.
+
+The browser renders the cues. Style them with the `::cue` pseudo-element.
+
+## Availability and constraints
+
+*   Captions availability is `'unavailable'` until the media has at least one caption or subtitle track; caption controls render nothing in that case.
+*   Cues load asynchronously. A track appears in `textTrackList` before its cues are parsed, so cue-driven UI fills in when the track finishes loading.
+*   Cross-origin track files require CORS: serve the VTT with CORS headers and set `crossOrigin` on the media element.
+*   Track selection UIs identify tracks by `label` and `language`; give every track both.
+*   `default` on a `<track>` makes the browser show it initially.
+
+## Common variations
+
+### Language selection menu
+
+For multiple languages, render a menu instead of a toggle.
+
+`useCaptionsOptions` provides the option list (including “Off”), the selected value, and availability:
+
+tsx
+
+```
+import { Menu, useCaptionsOptions } from '@videojs/react';
+
+function CaptionsMenu() {
+  const captions = useCaptionsOptions();
+  if (captions?.state.availability !== 'available') return null;
+
+  return (
+    <Menu.Root side="top" align="end">
+      <Menu.Trigger render={<button type="button" />}>Captions</Menu.Trigger>
+      <Menu.Content>
+        <Menu.RadioGroup value={captions.value} onValueChange={captions.setValue} aria-label="Captions">
+          {captions.options.map((option) => (
+            <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled}>
+              {option.label}
+            </Menu.RadioItem>
+          ))}
+        </Menu.RadioGroup>
+      </Menu.Content>
+    </Menu.Root>
+  );
+}
+```
+
+See the [CaptionsRadioGroup](../reference/captions-radio-group.md) reference for the complete pattern.
+
+## Troubleshooting
+
+### Captions don’t appear
+
+Confirm that:
+
+*   The track `kind` is `captions` or `subtitles`.
+*   The VTT file loads (check the network panel for the track request).
+*   The track is enabled: `default` on the track element, a CaptionsButton toggle, or `toggleSubtitles(true)`.
+
+### Captions work locally but not in production
+
+The track file is served from another origin without CORS headers. Serve it with `Access-Control-Allow-Origin` and set `crossOrigin` on the media element.
+
+### The selection menu is empty
+
+The media has no caption or subtitle tracks, so captions availability is `'unavailable'`. For streaming sources, confirm the manifest actually declares text tracks.
+
+## Related components
+
+*   [Captions button](../reference/captions-button.md)
+*   [Captions radio group](../reference/captions-radio-group.md)
+*   [Menu](../reference/menu.md)
+
+## Related API
+
+*   [Text track feature](../reference/feature-text-tracks.md)
+*   [useCaptionsOptions](../reference/use-captions-options.md)
+
+## Related guides
+
+*   [Show timeline thumbnail previews](./show-timeline-thumbnail-previews.md)
+*   [Media sources](../concepts/media-sources.md)
+*   [Accessibility](../concepts/accessibility.md)

package/docs/how-to/show-timeline-thumbnail-previews.md

@@ -0,0 +1,163 @@
+# Show timeline thumbnail previews
+
+Preview frames along the timeline while the user scrubs, powered by a storyboard track.
+
+Show preview frames along the timeline while the user scrubs, like YouTube’s seek previews.
+
+Using Mux?
+
+With [MuxVideo](../reference/mux-video.md), the storyboard track is wired up for you — skip adding the track and go straight to the slider thumbnail. For other services, generate the storyboard on their platform and add the track yourself.
+
+Note
+
+Using a pre-built [skin](../concepts/skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](../concepts/ui-components.md).
+
+## Recommended approach
+
+Add a `kind="metadata"` track labeled `thumbnails` whose cues reference storyboard images, then put a slider thumbnail inside the [TimeSlider](../reference/time-slider.md). Scrubbing shows the frame under the pointer; the thumbnail reads the pointer time from the slider, so it takes no props.
+
+App.tsx
+
+App.css
+
+```
+import { Container, createPlayer, Slider, TimeSlider } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop crossOrigin="anonymous">
+          <track kind="metadata" label="thumbnails" src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt" default />
+        </Video>
+        <TimeSlider.Root className="media-time-slider">
+          <TimeSlider.Track className="media-slider-track">
+            <TimeSlider.Fill className="media-slider-fill" />
+          </TimeSlider.Track>
+          <Slider.Thumbnail className="media-slider-thumbnail" />
+        </TimeSlider.Root>
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-time-slider {
+  position: absolute;
+  right: 10px;
+  bottom: 6px;
+  left: 10px;
+  display: flex;
+  align-items: center;
+  height: 20px;
+  cursor: pointer;
+}
+
+.media-slider-track {
+  position: absolute;
+  right: 0;
+  left: 0;
+  height: 4px;
+  background: rgba(255, 255, 255, 0.3);
+  border-radius: 9999px;
+  transition: height 150ms ease;
+}
+
+.media-time-slider[data-interactive] .media-slider-track {
+  height: 6px;
+}
+
+.media-slider-fill {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--media-slider-fill);
+  height: 100%;
+  background: white;
+  border-radius: 9999px;
+}
+
+/* Reveal the preview over the pointer while it is on the slider. */
+.media-slider-thumbnail {
+  position: absolute;
+  bottom: 100%;
+  left: var(--media-slider-pointer);
+  max-width: 160px;
+  margin-bottom: 8px;
+  pointer-events: none;
+  border-radius: 4px;
+  opacity: 0;
+  transform: translateX(-50%);
+  transition: opacity 150ms ease;
+}
+
+.media-time-slider[data-pointing] .media-slider-thumbnail {
+  opacity: 1;
+}
+
+.media-slider-thumbnail[data-hidden] {
+  display: none;
+}
+```
+
+## How it works
+
+*   Previews come from a storyboard: a `kind="metadata"` text track labeled `thumbnails` whose WebVTT cues map time ranges to image URLs (optionally with sprite coordinates). The [text track feature](../reference/feature-text-tracks.md) exposes these as `thumbnailCues` and `thumbnailTrackSrc`.
+*   The slider thumbnail renders the storyboard frame for the slider’s pointer position. While the pointer is over the slider, the slider sets `data-pointing` and the `--media-slider-pointer` CSS variable; the demo’s CSS uses them to reveal the preview and position it over the pointer.
+*   To render a storyboard frame outside the slider — a fixed preview for a chapter list, for example — use the standalone [Thumbnail](../reference/thumbnail.md) component with an explicit `time`.
+
+Each cue’s text is an image URL. An optional `#xywh=x,y,w,h` fragment crops one frame out of a sprite sheet:
+
+storyboard.vtt
+
+```
+WEBVTT
+
+00:00:00.000 --> 00:00:05.000
+storyboard.jpg#xywh=0,0,256,160
+
+00:00:05.000 --> 00:00:10.000
+storyboard.jpg#xywh=256,0,256,160
+```
+
+## Availability and constraints
+
+*   Thumbnails require a storyboard asset generated alongside the media; the player doesn’t extract frames from the video itself.
+*   Cross-origin storyboards need CORS headers, and `crossOrigin` on the media element for the track to load.
+*   Cues load asynchronously. The track appears before its cues are parsed, so previews fill in when the track finishes loading.
+*   Storyboard images download on demand; oversized sprite sheets hurt seek-preview responsiveness more than they help quality.
+
+## Troubleshooting
+
+### Thumbnails don’t appear while scrubbing
+
+Confirm the storyboard track is `kind="metadata"` with `label="thumbnails"` and has the `default` attribute — the browser leaves a non-default track disabled and never loads its cues. Then confirm the VTT loads (network panel) and cross-origin assets have CORS headers with `crossOrigin` set on the media element.
+
+### Thumbnails are blurry or slow
+
+Regenerate the storyboard with a larger frame size, or split giant sprite sheets into smaller images.
+
+## Related components
+
+*   [Thumbnail](../reference/thumbnail.md)
+*   [Time slider](../reference/time-slider.md)
+
+## Related API
+
+*   [Text track feature](../reference/feature-text-tracks.md)
+
+## Related guides
+
+*   [Add a poster and loading placeholder](./add-a-poster-and-loading-placeholder.md)
+*   [Show captions and subtitles](./show-captions-and-subtitles.md)

package/docs/how-to/use-picture-in-picture.md

@@ -0,0 +1,150 @@
+# Use picture-in-picture
+
+Pop the video into a floating window, with availability detection and state that tracks every entry path.
+
+Pop the video into a floating always-on-top window so it keeps playing while the user does something else.
+
+Note
+
+Using a pre-built [skin](../concepts/skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](../concepts/ui-components.md).
+
+## Recommended approach
+
+Add a [PiPButton](../reference/pip-button.md). It requests and exits picture-in-picture, reflects the current state, and renders nothing when picture-in-picture is unsupported.
+
+App.tsx
+
+App.css
+
+```
+import { Container, createPlayer, PiPButton } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player } = createPlayer({ features: videoFeatures });
+
+export default function BasicUsage() {
+  return (
+    <Player>
+      <Container className="media-container">
+        <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>}
+        />
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.media-container {
+  position: relative;
+}
+
+.media-container video {
+  width: 100%;
+}
+
+.media-pip-button {
+  position: absolute;
+  right: 10px;
+  bottom: 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);
+}
+```
+
+## How it works
+
+The [picture-in-picture feature](../reference/feature-pip.md) puts three things in player state.
+
+`pip` is `true` while the video is in a floating window. It tracks every way in and out — your button, the native controls, or a control the browser adds on its own.
+
+`pipAvailability` answers “can I offer this?” It starts as `'unavailable'`. Once the feature attaches to a media element, it settles to `'available'` or `'unsupported'`.
+
+`requestPictureInPicture()`, `exitPictureInPicture()`, and `togglePictureInPicture()` change the presentation. If the browser blocks a request, the returned promise rejects. In a browser with no picture-in-picture API, the actions resolve without changing anything.
+
+Picture-in-picture and fullscreen are exclusive: requesting one exits the other first.
+
+## Availability and constraints
+
+*   Show picture-in-picture controls only when `pipAvailability` is `'available'`. PiPButton handles this for you.
+*   Requests must come from a user gesture; browsers reject requests outside one.
+*   Firefox 153 (July 2026) added the programmatic picture-in-picture API. Earlier versions, including Firefox ESR 140, report `'unsupported'` even though they offer their own built-in picture-in-picture toggle to users.
+*   On iOS, picture-in-picture is supported on iPhone and iPad through the WebKit presentation mode; the player handles this path for you.
+*   The browser owns the floating window: its size, position, and built-in controls aren’t yours to style.
+*   The user can close the window or return the video at any time. React to `pip` state instead of assuming your button is the only entry and exit.
+
+## Common variations
+
+### Request picture-in-picture from app logic
+
+Enter picture-in-picture when the user scrolls the player out of view or navigates within your app. This still requires a recent user gesture in most browsers, so tie it to an interaction:
+
+tsx
+
+```
+import { Container } from '@videojs/react';
+import { usePlayer, Video, VideoPlayer } from '@videojs/react/video';
+
+function WatchElsewhereButton() {
+  const store = usePlayer();
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        store.requestPictureInPicture().catch(() => {
+          // Rejected: no video data yet, or blocked by the browser.
+        });
+      }}
+    >
+      Keep watching while you browse
+    </button>
+  );
+}
+
+export default function App() {
+  return (
+    <VideoPlayer>
+      <Container>
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
+        <WatchElsewhereButton />
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+
+## Troubleshooting
+
+### The picture-in-picture button doesn’t render
+
+`pipAvailability` is `'unsupported'` — the browser has no programmatic picture-in-picture API (Firefox before 153), or the media isn’t a video.
+
+### The request rejects
+
+The video has no data yet (wait for it to be ready), the call wasn’t tied to a user gesture, or the browser blocked it. Handle the rejection rather than assuming entry succeeded.
+
+### State is wrong after the user closes the floating window
+
+Read `pip` from player state instead of tracking entry and exit yourself; it stays in sync with every path in and out of picture-in-picture.
+
+## Related components
+
+*   [PiP button](../reference/pip-button.md)
+
+## Related API
+
+*   [Picture-in-picture feature](../reference/feature-pip.md)
+
+## Related guides
+
+*   [Go fullscreen and lock orientation](./go-fullscreen-and-lock-orientation.md)
+*   [Cast to AirPlay and Chromecast](./cast-to-airplay-and-chromecast.md)