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

package/docs/reference/use-button.md

@@ -0,0 +1,124 @@
+# useButton
+
+Hook for creating accessible button components with keyboard and pointer interaction
+
+`useButton` provides button behavior including keyboard activation and accessibility checks. It returns a `getButtonProps` function for spreading onto a `<button>` element and a `buttonRef` for validation.
+
+`getButtonProps` merges internal button props (click/keyboard handlers, disabled state) with any external props you pass in. Use [`renderElement`](./render-element.md) to render the button with state-driven props and render prop support. In development mode, `buttonRef` warns if the rendered element is not a `<button>`.
+
+## Examples
+
+### Basic Usage
+
+Activated 0 timesDisabled
+
+App.tsx
+
+App.css
+
+```
+import { useButton } from '@videojs/react';
+import type { Ref } from 'react';
+import { useState } from 'react';
+
+export default function BasicUsage() {
+  const [count, setCount] = useState(0);
+  const [disabled, setDisabled] = useState(false);
+
+  const { getButtonProps, buttonRef } = useButton({
+    displayName: 'ActivateButton',
+    onActivate: () => setCount((c) => c + 1),
+    isDisabled: () => disabled,
+  });
+
+  return (
+    <div className="demo">
+      <button ref={buttonRef as Ref<HTMLButtonElement>} {...getButtonProps()} className="button" disabled={disabled}>
+        Activated {count} times
+      </button>
+      <label className="label">
+        <input type="checkbox" checked={disabled} onChange={(e) => setDisabled(e.target.checked)} />
+        Disabled
+      </label>
+    </div>
+  );
+}
+```
+```
+.demo {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  padding: 16px;
+}
+
+.button {
+  align-self: flex-start;
+  padding: 8px 20px;
+  font-variant-numeric: tabular-nums;
+  cursor: pointer;
+  background: #f5f5f5;
+  border: 1px solid #ccc;
+  border-radius: 6px;
+  transition: opacity 0.2s;
+}
+
+.button[disabled] {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+.label {
+  display: flex;
+  gap: 6px;
+  align-items: center;
+  font-size: 0.875rem;
+  color: #6b7280;
+}
+```
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`params*`
+
+`UseButtonParameters`
+
+`—`
+
+▸
+
+Description
+
+Button configuration with activation handler and disabled check.
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`getButtonProps`
+
+`function`
+
+▸
+
+Type
+
+`((externalProps: ComponentPropsWithRef<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement> | undefined) => DetailedHTMLProps<ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>)`
+
+`buttonRef`
+
+`Ref<HTMLElement>`

package/docs/reference/use-captions-options.md

@@ -0,0 +1,59 @@
+# useCaptionsOptions
+
+Hook to build captions menu options from the player text track state
+
+`useCaptionsOptions` returns the currently showing caption track, the available options (starting with an `Off` option), and a `setValue` callback for wiring caption selection into a menu. It returns `null` when the [text tracks feature](./feature-text-tracks.md) is not configured.
+
+CaptionsMenu.tsx
+
+```
+import { Menu, useCaptionsOptions } from "@videojs/react";
+
+function CaptionsMenu() {
+  const captions = useCaptionsOptions();
+  if (captions?.state.availability !== "available") return null;
+
+  return (
+    <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.ItemIndicator checked={option.value === captions.value} />
+        </Menu.RadioItem>
+      ))}
+    </Menu.RadioGroup>
+  );
+}
+```
+
+Option labels use the track label, then language, then kind. Pass `formatTrack` to customize the visible labels. The result also exposes `showMenu`, which is `true` when more than one caption or subtitle track is available — the same threshold [CaptionsButton](./captions-button.md) uses to open a menu instead of toggling in `menuTrigger` mode.
+
+See [CaptionsRadioGroup](./captions-radio-group.md) for the component-level pattern, and [Menu](./menu.md) for a complete settings menu example.
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`props`
+
+`CaptionsOptionsProps`
+
+`—`
+
+▸
+
+Description
+
+Optional `label`, `formatTrack`, and `disabled` overrides.
+
+### Return Value
+
+`CaptionsOptionsResult | null`

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

@@ -0,0 +1,42 @@
+# useContainerAttach
+
+Hook to register a custom container element with the player context
+
+`useContainerAttach` returns a setter function for registering a DOM element as the player’s container. The built-in `Container` uses this internally; you only need it when building a custom container element.
+
+CustomContainer.tsx
+
+```
+import { useContainerAttach } from "@videojs/react";
+
+function CustomContainer({ children }: { children: React.ReactNode }) {
+  const setContainer = useContainerAttach();
+  return <div ref={setContainer}>{children}</div>;
+}
+```
+
+## Who needs this
+
+You only need `useContainerAttach` if you’re replacing the built-in `Container` with a custom element. For example, if you’re building a container with custom fullscreen behavior or a non-standard layout boundary.
+
+For standard player layouts, use the built-in `Container`.
+
+## Safe outside Player
+
+Returns `undefined` when called outside `Player`. Passing `undefined` to `ref` is harmless in React. Check the return value if your component needs to know whether it’s inside a player.
+
+## API Reference
+
+### Return Value
+
+Type
+
+Details
+
+`Dispatch<SetStateAction<HTMLElement |...`
+
+▸
+
+Type
+
+`Dispatch<SetStateAction<HTMLElement | null>> | undefined`

package/docs/reference/use-locale.md

@@ -0,0 +1,124 @@
+# useLocale
+
+React hook that returns the active BCP 47 locale from the nearest I18nProvider
+
+`useLocale` returns the resolved BCP 47 tag from the nearest [`I18nProvider`](./i18n-provider.md), or `'en'` when none is mounted.
+
+Use it when UI copy depends on the active locale outside the translator, for example formatting or caption language hooks.
+
+## Example
+
+Switch the provider locale to see `useLocale` supply the BCP 47 tag used to format a date.
+
+Localeen-USfr-FRja-JP
+
+Active locale
+
+en-US
+
+Formatted date
+
+January 15, 2026
+
+App.tsx
+
+App.css
+
+```
+import { I18nProvider, useLocale } from '@videojs/react/i18n';
+import { useState } from 'react';
+
+import './BasicUsage.css';
+
+const locales = ['en-US', 'fr-FR', 'ja-JP'] as const;
+type Locale = (typeof locales)[number];
+
+function LocaleDetails() {
+  const locale = useLocale();
+  const date = new Intl.DateTimeFormat(locale, {
+    dateStyle: 'long',
+    timeZone: 'UTC',
+  }).format(new Date('2026-01-15T12:00:00Z'));
+
+  return (
+    <dl className="react-use-locale-basic__output">
+      <div>
+        <dt>Active locale</dt>
+        <dd>{locale}</dd>
+      </div>
+      <div>
+        <dt>Formatted date</dt>
+        <dd lang={locale}>{date}</dd>
+      </div>
+    </dl>
+  );
+}
+
+export default function BasicUsage() {
+  const [locale, setLocale] = useState<Locale>('en-US');
+
+  return (
+    <div className="react-use-locale-basic">
+      <label>
+        Locale
+        <select value={locale} onChange={(event) => setLocale(event.currentTarget.value as Locale)}>
+          {locales.map((value) => (
+            <option key={value}>{value}</option>
+          ))}
+        </select>
+      </label>
+      <I18nProvider locale={locale}>
+        <LocaleDetails />
+      </I18nProvider>
+    </div>
+  );
+}
+```
+```
+.react-use-locale-basic {
+  display: grid;
+  gap: 16px;
+  padding: 16px;
+}
+
+.react-use-locale-basic label,
+.react-use-locale-basic__output div {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.react-use-locale-basic select {
+  padding: 4px 8px;
+}
+
+.react-use-locale-basic__output {
+  display: grid;
+  gap: 8px;
+  margin: 0;
+}
+
+.react-use-locale-basic__output dt {
+  color: #6b7280;
+}
+
+.react-use-locale-basic__output dd {
+  margin: 0;
+}
+```
+
+## API Reference
+
+### Return Value
+
+Type
+
+Details
+
+`string & object | 'ar' | 'az' | 'bs' ...`
+
+▸
+
+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' | 'id' | 'it' | 'ja' | 'ko' | 'lt' | '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'`

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

@@ -0,0 +1,46 @@
+# useMediaAttach
+
+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.
+
+CustomMedia.tsx
+
+```
+import { useMediaAttach } from "@videojs/react";
+
+function CustomMedia({ src }: { src: string }) {
+  const setMedia = useMediaAttach();
+  return <video ref={setMedia} src={src} />;
+}
+```
+
+## Who needs this
+
+You only need `useMediaAttach` if you’re replacing the built-in `<Video>` or `<Audio>` components with a custom element. For example, if you’re…
+
+*   Wrapping a third-party video player
+*   Using a `<canvas>` or WebGL-based renderer
+*   Building a custom `<audio>` element with additional markup
+
+For standard `<video>` and `<audio>` playback, use the built-in components.
+
+## Safe outside Player
+
+Returns `undefined` when called outside `Player`. Check the return value before using it – this avoids crashes in components that may render outside the player tree.
+
+## API Reference
+
+### Return Value
+
+Type
+
+Details
+
+`Dispatch<SetStateAction<Media | null>...`
+
+▸
+
+Type
+
+`Dispatch<SetStateAction<Media | null>> | undefined`

package/docs/reference/use-media.md

@@ -0,0 +1,112 @@
+# useMedia
+
+Hook to access the media object from within a Player
+
+The `useMedia` hook returned by [`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 the matching `Player`. The media object becomes available after a `<Video>` or `<Audio>` component mounts inside the player tree. To attach a custom media element instead of the built-in components, see [`useMediaAttach`](./use-media-attach.md).
+
+tsx
+
+```
+const { Player, useMedia } = createPlayer({ features: videoFeatures });
+```
+
+## Examples
+
+### Basic Usage
+
+App.tsx
+
+App.css
+
+```
+import { Container, createPlayer, isMediaSourceCapable, isMediaVideoDimensionsCapable } from '@videojs/react';
+import { Video, videoFeatures } from '@videojs/react/video';
+
+const { Player, useMedia } = createPlayer({
+  features: videoFeatures,
+});
+
+function MediaInfo() {
+  const media = 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>
+      <Container className="media-container">
+        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
+        <MediaInfo />
+      </Container>
+    </Player>
+  );
+}
+```
+```
+.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
+
+### Return Value
+
+`Media | null`

package/docs/reference/use-playback-rate-options.md

@@ -0,0 +1,59 @@
+# usePlaybackRateOptions
+
+Hook to build playback rate menu options from the player playback rate state
+
+`usePlaybackRateOptions` returns the current playback rate, the available options, and `setRate` / `setValue` callbacks for wiring rate selection into a menu. It returns `null` when the [playback rate feature](./feature-playback-rate.md) is not configured.
+
+SpeedMenu.tsx
+
+```
+import { Menu, usePlaybackRateOptions } from "@videojs/react";
+
+function SpeedMenu() {
+  const playbackRate = usePlaybackRateOptions();
+  if (playbackRate?.state.availability !== "available") return null;
+
+  return (
+    <Menu.RadioGroup value={playbackRate.value} onValueChange={playbackRate.setValue} aria-label="Speed">
+      {playbackRate.options.map((option) => (
+        <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled}>
+          {option.label}
+          <Menu.ItemIndicator checked={option.value === playbackRate.value} />
+        </Menu.RadioItem>
+      ))}
+    </Menu.RadioGroup>
+  );
+}
+```
+
+Options come from the player’s configured playback rates. Labels default to the rate followed by a multiplication sign (e.g. `1.5×`); pass `formatRate` to customize them. `setValue` accepts an option’s string value, while `setRate` accepts a number directly.
+
+See [PlaybackRateRadioGroup](./playback-rate-radio-group.md) for the component-level pattern, and [Menu](./menu.md) for a complete settings menu example.
+
+## API Reference
+
+### Parameters
+
+Parameter
+
+Type
+
+Default
+
+Details
+
+`props`
+
+`PlaybackRateOptionsProps`
+
+`—`
+
+▸
+
+Description
+
+Optional `label`, `formatRate`, and `disabled` overrides.
+
+### Return Value
+
+`PlaybackRateOptionsResult | null`

package/docs/reference/use-player-context.md

@@ -0,0 +1,90 @@
+# usePlayerContext
+
+Hook to access the full player context value
+
+`usePlayerContext` returns the full `PlayerContextValue` object for lower-level integrations that need direct access to player context fields.
+
+DebugPanel.tsx
+
+```
+import { usePlayerContext } from "@videojs/react";
+
+function DebugPanel() {
+  const { store, media, container } = usePlayerContext();
+
+  return (
+    <pre>
+      {JSON.stringify(
+        {
+          hasStore: !!store,
+          hasMedia: !!media,
+          hasContainer: !!container,
+          tagName: media?.tagName,
+        },
+        null,
+        2,
+      )}
+    </pre>
+  );
+}
+```
+
+Throws an error if called outside a Player `Provider`.
+
+### Prefer higher-level hooks
+
+For most use cases, use the focused hooks instead:
+
+Need
+
+Hook
+
+Store access with selector
+
+[`usePlayer`](./use-player.md)
+
+Current media element
+
+[`useMedia`](./use-media.md)
+
+Attach custom media
+
+[`useMediaAttach`](./use-media-attach.md)
+
+These hooks read from the same context internally. `usePlayerContext` exposes the raw context value – use it when you need multiple context fields in one call or when building a custom abstraction over the player context.
+
+## API Reference
+
+### Return Value
+
+Property
+
+Type
+
+Details
+
+`store`
+
+`BaseStore & UnknownState`
+
+`media`
+
+`Media | null`
+
+`setMedia`
+
+`Dispatch<SetStateAction<Media | null>>`
+
+`container`
+
+`MediaContainer | null`
+
+`setContainer`
+
+`Dispatch<SetStateAction<HTMLElement |...`
+
+▸
+
+Type
+
+`Dispatch<SetStateAction<HTMLElement | null>>`