@videojs/react 10.0.0-beta.9 → 10.0.0-rc.2

package/docs/how-to/play-live-streams.md

@@ -0,0 +1,147 @@
+# Play live streams
+
+Play live streams with live-edge tracking, DVR windows, and stream-type detection.
+
+Play live streams: show a live badge, jump to the live edge, and support DVR windows when the stream allows scrubbing back.
+
+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).
+
+## Installation
+
+The examples use HlsJsVideo, so install hls.js with the framework façade:
+
+bash
+
+```
+pnpm add @videojs/react @videojs/hlsjs-video
+```
+
+## Recommended approach
+
+Use the live feature bundle with a streaming media element, and give users a `LiveButton`: it shows whether playback is at the live edge and seeks back to it when activated.
+
+tsx
+
+```
+import { Container, LiveButton } from '@videojs/react';
+import { LiveVideoPlayer } from '@videojs/react/live-video';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+
+export default function App() {
+  return (
+    <LiveVideoPlayer>
+      <Container>
+        <HlsJsVideo src="https://your-stream.example.com/live.m3u8" autoPlay muted playsInline />
+        <LiveButton render={(props, state) => <button {...props}>{state.liveEdge ? 'LIVE' : 'Go live'}</button>} />
+      </Container>
+    </LiveVideoPlayer>
+  );
+}
+```
+
+The examples use [`HlsJsVideo`](../reference/hlsjs-video.md), but any streaming media component works here, including the smaller default [`HlsVideo`](../reference/hls-video.md). Start with the default and switch engines only if your stream needs it.
+
+The `liveVideoFeatures` bundle mirrors [`videoFeatures`](../concepts/features.md) but adds the live feature and drops playback rate (not meaningful for live), quality selection, and audio-track selection. The live presets also ship skins without a time slider, duration display, or current-time display.
+
+Both bundles are plain arrays, so extending one is a spread:
+
+tsx
+
+```
+import { createPlayer, streamTypeFeature } from '@videojs/react';
+import { liveVideoFeatures } from '@videojs/react/live-video';
+
+const { Player } = createPlayer({ features: [...liveVideoFeatures, streamTypeFeature] });
+```
+
+## How it works
+
+Two features describe liveness:
+
+*   The [stream type feature](../reference/feature-stream-type.md) reports `streamType`: `'live'`, `'on-demand'`, or `'unknown'`. Streaming media derives it from manifest metadata; plain media elements fall back to duration-based detection. `liveVideoFeatures` does not include it; add `streamTypeFeature` to the player’s features when you need `streamType`.
+*   The [live feature](../reference/feature-live.md) reports two values:
+    *   `liveEdgeStart` is where “live” begins on the timeline. When the playhead is at or past this time, the viewer is watching live; behind it, they’re watching earlier moments of the stream.
+    *   `targetLiveWindow` is how far back the stream lets viewers rewind. `0` means a plain live stream that stays at the edge. `Infinity` means full DVR: rewind as far as the recording goes. `NaN` means the stream isn’t live, or the player doesn’t know yet.
+
+The [time feature](../reference/feature-time.md) adjusts for live playback: `duration` reports the live edge (the end of the seekable range) and keeps growing as the stream continues.
+
+LiveButton reads this state: it renders as an active “go to live” control while playback is behind the edge, seeks to the edge on activation, and goes inactive at the edge. Until the media reports a `seekable` range — before metadata loads, or for non-live media — the button is disabled (`data-disabled`) because there is no edge to seek to. Custom live UIs should treat “behind the edge” and “actionable” as separate states.
+
+## Availability and constraints
+
+*   `liveEdgeStart` and `targetLiveWindow` come from media that implements the live capability — the hls.js-based media elements. With plain media elements, stream type falls back to duration-based detection and `liveEdgeStart` stays `NaN`.
+*   Live playback drifts behind the edge when the network stalls or the tab is backgrounded. Always give users a path back to the edge.
+*   Seeking makes sense only for DVR streams (`targetLiveWindow` of `Infinity`). For standard-latency streams, omit the time slider.
+*   Playback rate control isn’t meaningful for live; `liveVideoFeatures` omits it.
+
+## Common variations
+
+### DVR: let users scrub back
+
+For streams with a DVR window, give users a [TimeSlider](../reference/time-slider.md). The live preset skins don’t include one, so add it to your own UI or [eject the skin](./customize-skins.md#eject-and-edit-a-skin). The slider tracks the sliding window automatically because `duration` follows the live edge.
+
+### Switch UI by stream type
+
+Render live or on-demand controls from `streamType` when one player handles both kinds of content. Add `streamTypeFeature` to the player’s features; `liveVideoFeatures` does not include it:
+
+The preset `LiveVideoPlayer` comes with a fixed feature set. To change it, build the player yourself with [`createPlayer`](../reference/create-player.md) — the escape hatch for custom feature sets:
+
+tsx
+
+```
+import { Container, createPlayer, LiveButton, streamTypeFeature } from '@videojs/react';
+import { liveVideoFeatures } from '@videojs/react/live-video';
+import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
+
+const { Player, usePlayer } = createPlayer({ features: [...liveVideoFeatures, streamTypeFeature] });
+
+function LiveBadge() {
+  const streamType = usePlayer((s) => s.streamType);
+  if (streamType !== 'live') return null;
+
+  return <LiveButton render={(props, state) => <button {...props}>{state.liveEdge ? 'LIVE' : 'Go live'}</button>} />;
+}
+
+export default function App() {
+  return (
+    <Player>
+      <Container>
+        <HlsJsVideo src="https://your-stream.example.com/live.m3u8" autoPlay muted playsInline />
+        <LiveBadge />
+      </Container>
+    </Player>
+  );
+}
+```
+
+## Troubleshooting
+
+### The live badge never activates
+
+`streamType` isn’t `'live'`. Confirm the player’s features include `streamTypeFeature` (`liveVideoFeatures` does not include it, so `streamType` reads as `undefined`), the source is a live manifest, and it plays through a live-capable media element such as [HlsJsVideo](../reference/hlsjs-video.md).
+
+### Playback keeps falling behind the edge
+
+Network throughput can’t sustain the stream, or the tab was backgrounded. LiveButton returns users to the edge; for lower drift, review the stream’s latency configuration on the encoder side.
+
+### The time slider behaves oddly on a live stream
+
+Standard-latency live streams have no meaningful seek range. Show the slider only for DVR streams (`targetLiveWindow` of `Infinity`).
+
+## Related components
+
+*   [Time slider](../reference/time-slider.md)
+*   [Buffering indicator](../reference/buffering-indicator.md)
+
+## Related API
+
+*   [Live feature](../reference/feature-live.md)
+*   [Stream type feature](../reference/feature-stream-type.md)
+*   [Time feature](../reference/feature-time.md)
+*   [HlsJsVideo](../reference/hlsjs-video.md)
+
+## Related guides
+
+*   [Media sources](../concepts/media-sources.md)

package/docs/how-to/remember-user-preferences.md

@@ -0,0 +1,180 @@
+# Remember user preferences
+
+Persist volume, caption, and quality preferences across sessions by subscribing to player state.
+
+Persist player preferences — volume, muted, captions, quality — so returning users get the setup they left with.
+
+The player doesn’t persist preferences itself today. Player state gives you everything needed to wire persistence to the storage you choose — local storage, your backend, or per-profile settings.
+
+## Recommended approach
+
+Subscribe to the state you want to remember, write it to storage when it changes, and restore it once the store attaches to the media.
+
+tsx
+
+```
+import { useEffect, useRef, useState } from 'react';
+import { Container } from '@videojs/react';
+import { usePlayer, Video, VideoPlayer } from '@videojs/react/video';
+
+const STORAGE_KEY = 'player:volume';
+
+// Local storage can be unavailable (private modes), so guard reads and writes.
+function readSaved() {
+  try {
+    return JSON.parse(localStorage.getItem(STORAGE_KEY) ?? 'null');
+  } catch {
+    return null;
+  }
+}
+
+function save(prefs: { volume: number; muted: boolean }) {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(prefs));
+  } catch {
+    // Storage unavailable; skip persistence.
+  }
+}
+
+function VolumePersistence() {
+  const store = usePlayer();
+  const { volume, muted } = usePlayer((s) => ({ volume: s.volume, muted: s.muted }));
+  // Read the saved value once, before the save effect below can write.
+  const [saved] = useState(readSaved);
+  const restored = useRef(false);
+
+  // Save on change, once the restore has run.
+  useEffect(() => {
+    if (!restored.current) return;
+    save({ volume, muted });
+  }, [volume, muted]);
+
+  // Restore once the store attaches to the media; actions throw before that.
+  useEffect(() => {
+    const restore = () => {
+      if (!store.target) return false;
+      if (saved) {
+        store.setVolume(saved.volume);
+        // setVolume above zero unmutes, so mute again if that's the saved preference.
+        // At volume zero the player already counts as muted, and toggling would unmute.
+        if (saved.muted && saved.volume > 0) store.toggleMuted();
+      }
+      restored.current = true;
+      return true;
+    };
+    if (restore()) return;
+    const unsubscribe = store.subscribe(() => {
+      if (restore()) unsubscribe();
+    });
+    return unsubscribe;
+  }, [store, saved]);
+
+  return null;
+}
+
+export default function App() {
+  return (
+    <VideoPlayer>
+      <Container>
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline />
+        <VolumePersistence />
+      </Container>
+    </VideoPlayer>
+  );
+}
+```
+
+## How it works
+
+*   Player state is the single source of truth: it already reflects every change, whatever caused it — your UI, keyboard shortcuts, native controls, or scripts.
+*   `store.subscribe(callback)` fires on any state change. Notifications are batched per microtask, so rapid changes (a volume drag) produce one callback per tick, which keeps storage writes cheap. There is no per-key subscription on the store: read the state and diff the slice you care about.
+*   In React, `usePlayer(selector)` re-renders only when the selected value changes; pairing it with an effect is the idiomatic save path.
+*   Feature selectors exported by `@videojs/html` and `@videojs/react` (`selectVolume`, `selectTextTrack`, `selectQuality`, and the rest) read a feature’s slice from any store, returning `undefined` when the feature isn’t present.
+*   Restore through the feature actions (`setVolume`, `toggleMuted`, `selectSubtitlesTrack`, `selectVideoRendition`) rather than poking the media element, so state and UI stay consistent.
+*   Actions need an attached media target: calling one before the store attaches throws. Check `store.target` and defer the restore until it is set, as the examples do.
+
+## Availability and constraints
+
+*   Nothing persists by default: volume resets to the media element’s value, captions to the track markup, quality to automatic, on every load.
+*   `setVolume` clamps to 0–1 and unmutes when setting a value above zero; restore volume first, then toggle `muted` back on when the saved preference is muted, as the examples do. Skip the toggle when the saved volume is zero: the player treats volume zero as muted, so toggling would unmute and raise the volume. Don’t compare against store state right after calling an action: notifications batch per microtask, so that state is still stale.
+*   Restore track and quality selections after the media exposes them: track and rendition lists arrive when the media loads, not at player creation. Subscribe and apply when the saved entry appears in the list.
+*   Programmatic volume control is unavailable on some platforms (after attach, iOS Safari reports `volumeAvailability: 'unsupported'`); volume persistence quietly does nothing there.
+*   Local storage is per-origin and can be unavailable (private modes, embedded contexts); guard reads and writes accordingly.
+
+## Common variations
+
+### Persist caption preference
+
+Save the showing track’s `language` (not its generated id, which can change between sources), or `'off'` when the user turns captions off. Restoring is two phases: while the media loads, assert the saved preference whenever the track modes drift from it, because browsers can auto-enable a track of their own during loading. Once the media can play (`canPlay`), treat every change as the user’s choice and save it. A restore that re-runs forever would keep overriding the user; one that runs only once can get overridden by the browser.
+
+tsx
+
+```
+function CaptionsPersistence() {
+  const store = usePlayer();
+  const { tracks, canPlay } = usePlayer((s) => ({ tracks: s.textTrackList, canPlay: s.canPlay }));
+  const [saved] = useState(() => localStorage.getItem('player:captions'));
+  const restored = useRef(false);
+
+  useEffect(() => {
+    const subtitles = tracks.filter((t) => t.kind === 'captions' || t.kind === 'subtitles');
+    if (!subtitles.length) return;
+
+    // Restore phase: assert the saved preference until the media can play.
+    if (!restored.current) {
+      const desired = saved === 'off' ? undefined : subtitles.find((t) => t.language === saved);
+      if (saved && (desired || saved === 'off')) {
+        const applied = subtitles.every((t) => (t.mode === 'showing') === (t.id === desired?.id));
+        if (!applied) {
+          store.selectSubtitlesTrack(desired?.id ?? 'off');
+          return;
+        }
+      }
+      if (!canPlay) return;
+      restored.current = true;
+    }
+
+    // Save phase: the showing track's language, or 'off'.
+    const showing = subtitles.find((t) => t.mode === 'showing');
+    localStorage.setItem('player:captions', showing ? showing.language : 'off');
+  }, [store, tracks, canPlay, saved]);
+
+  return null;
+}
+```
+
+### Persist to your backend
+
+Swap `localStorage` for an API call; the subscription pattern is identical. Debounce writes beyond the built-in microtask batching if your storage is remote.
+
+## Troubleshooting
+
+### The saved volume doesn’t apply
+
+Restore runs before the store attaches, or the platform doesn’t allow programmatic volume (check `volumeAvailability`). Apply after `store.target` is set, as in the examples.
+
+### The saved caption track doesn’t select
+
+The track list wasn’t loaded yet when you restored, or you saved a generated track id instead of a stable property like `language`. React to `textTrackList` changes and match on language.
+
+### Storage writes fire constantly while dragging the volume slider
+
+Notifications batch per microtask, but a drag still produces many ticks. Debounce the write if the churn matters for your storage target.
+
+## Related components
+
+*   [Volume slider](../reference/volume-slider.md)
+*   [Captions radio group](../reference/captions-radio-group.md)
+*   [Quality radio group](../reference/quality-radio-group.md)
+
+## Related API
+
+*   [usePlayer](../reference/use-player.md)
+*   [useStore](../reference/use-store.md)
+*   [Volume feature](../reference/feature-volume.md)
+*   [Text track feature](../reference/feature-text-tracks.md)
+
+## Related guides
+
+*   [Show captions and subtitles](./show-captions-and-subtitles.md)
+*   [Add a quality selector](./add-quality-selector.md)

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

@@ -0,0 +1,182 @@
+# 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
+
+Set `visibility="always"` on [Controls](../reference/controls.md). The controls stay visible and report the user as active while the feature keeps tracking activity for anything else that needs it. The packaged audio skins use this mode.
+
+tsx
+
+```
+<Controls.Root visibility="always">
+  <Controls.Content className="controls">...</Controls.Content>
+</Controls.Root>
+```
+
+### 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)