@videojs/react 10.0.0-beta.27 → 10.0.0-beta.29

package/dist/dev/utils/use-render.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-render.js","names":[],"sources":["../../../src/utils/use-render.tsx"],"sourcesContent":["'use client';\n\nimport { getStateDataAttrs, type StateAttrMap } from '@videojs/core/dom';\nimport { isFunction } from '@videojs/utils/predicate';\nimport type { CSSProperties, ReactElement, Ref } from 'react';\nimport { cloneElement, createElement, isValidElement } from 'react';\nimport { mergeProps } from './merge-props';\nimport type { HTMLProps, RenderProp } from './types';\nimport { composeRefs } from './use-composed-refs';\n\n/** Check if a value is a render prop (function or React element). */\nexport function isRenderProp(value: unknown): value is RenderProp<unknown> {\n  return isFunction(value) || isValidElement(value);\n}\n\ntype IntrinsicTagName = keyof React.JSX.IntrinsicElements;\n\nexport interface UseRenderComponentProps<State> {\n  className?: string | ((state: State) => string | undefined) | undefined;\n  style?: CSSProperties | ((state: State) => CSSProperties | undefined) | undefined;\n  render?: RenderProp<State> | undefined;\n}\n\nexport interface UseRenderParameters<State, RenderedElementType extends Element> {\n  state: State;\n  ref?: Ref<RenderedElementType> | Ref<RenderedElementType>[] | undefined;\n  props?: object | object[] | undefined;\n  stateAttrMap?: StateAttrMap<State> | undefined;\n}\n\nfunction resolveClassName<State>(\n  className: string | ((state: State) => string | undefined) | undefined,\n  state: State\n): string | undefined {\n  return isFunction(className) ? className(state) : className;\n}\n\nfunction resolveStyle<State>(\n  style: CSSProperties | ((state: State) => CSSProperties | undefined) | undefined,\n  state: State\n): CSSProperties | undefined {\n  return isFunction(style) ? style(state) : style;\n}\n\nfunction getElementRef(element: ReactElement): Ref<unknown> | undefined {\n  // React 19+ uses element.props.ref, older versions use element.ref\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const elementAny = element as any;\n  return elementAny.ref ?? elementAny.props?.ref;\n}\n\n/**\n * Render a UI component element.\n *\n * Handles:\n * - Default tag rendering\n * - Render prop (element or function)\n * - Props merging (event handlers chained, className concatenated, style merged)\n * - Ref composition\n * - className/style as functions of state\n *\n * @public\n * @example\n * ```tsx\n * return renderElement('button', componentProps, {\n *   state,\n *   ref: [forwardedRef, buttonRef],\n *   props: [{ type: 'button' }, elementProps, getButtonProps],\n * });\n * ```\n */\nexport function renderElement<\n  State extends object,\n  RenderedElementType extends Element,\n  TagName extends IntrinsicTagName,\n>(\n  element: TagName,\n  componentProps: UseRenderComponentProps<State>,\n  params: UseRenderParameters<State, RenderedElementType>\n): ReactElement | null {\n  const { className: classNameProp, style: styleProp, render } = componentProps;\n  const { state, ref, props, stateAttrMap } = params;\n\n  // Resolve className and style if they're functions\n  const className = resolveClassName(classNameProp, state);\n  const style = resolveStyle(styleProp, state);\n\n  // Generate data attributes only when a component explicitly opts in with a\n  // mapping. State is still passed to render/className/style callbacks.\n  const stateDataAttrs = stateAttrMap ? getStateDataAttrs(state, stateAttrMap) : {};\n\n  // Merge: state data attrs first, then props (so props can override)\n  const propsArray = Array.isArray(props) ? props : props ? [props] : [];\n  const mergedProps = mergeProps(stateDataAttrs, ...(propsArray as Record<string, unknown>[]));\n\n  if (className !== undefined) {\n    // Add resolved className and style\n    mergedProps.className = mergedProps.className ? `${mergedProps.className} ${className}` : className;\n  }\n\n  if (style !== undefined) {\n    mergedProps.style = mergedProps.style ? { ...(mergedProps.style as CSSProperties), ...style } : style;\n  }\n\n  if (isFunction(render)) {\n    // Render function: call with props and state\n    const mergedRef = composeRefs(ref, mergedProps.ref);\n    return render({ ...mergedProps, ref: mergedRef } as HTMLProps, state);\n  }\n\n  if (isValidElement(render)) {\n    const elementRef = getElementRef(render);\n\n    const mergedRef = composeRefs(ref, mergedProps.ref, elementRef);\n\n    const elementProps = mergeProps(mergedProps, render.props as Record<string, unknown>);\n    elementProps.ref = mergedRef;\n\n    return cloneElement(render, elementProps);\n  }\n\n  // Default tag\n  const mergedRef = composeRefs(ref, mergedProps.ref);\n  mergedProps.ref = mergedRef;\n\n  return createElement(element, mergedProps);\n}\n\nexport namespace renderElement {\n  export type ComponentProps<State> = UseRenderComponentProps<State>;\n  export type Parameters<State, RenderedElementType extends Element> = UseRenderParameters<State, RenderedElementType>;\n}\n"],"mappings":";;;;;;;;AAWA,SAAgB,aAAa,OAA8C;CACzE,OAAO,WAAW,KAAK,KAAK,eAAe,KAAK;AAClD;AAiBA,SAAS,iBACP,WACA,OACoB;CACpB,OAAO,WAAW,SAAS,IAAI,UAAU,KAAK,IAAI;AACpD;AAEA,SAAS,aACP,OACA,OAC2B;CAC3B,OAAO,WAAW,KAAK,IAAI,MAAM,KAAK,IAAI;AAC5C;AAEA,SAAS,cAAc,SAAiD;CAGtE,MAAM,aAAa;CACnB,OAAO,WAAW,OAAO,WAAW,OAAO;AAC7C;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,cAKd,SACA,gBACA,QACqB;CACrB,MAAM,EAAE,WAAW,eAAe,OAAO,WAAW,WAAW;CAC/D,MAAM,EAAE,OAAO,KAAK,OAAO,iBAAiB;CAG5C,MAAM,YAAY,iBAAiB,eAAe,KAAK;CACvD,MAAM,QAAQ,aAAa,WAAW,KAAK;CAQ3C,MAAM,cAAc,WAJG,eAAe,kBAAkB,OAAO,YAAY,IAAI,CAAC,GAIjC,GAD5B,MAAM,QAAQ,KAAK,IAAI,QAAQ,QAAQ,CAAC,KAAK,IAAI,CAAC,CACsB;CAE3F,IAAI,cAAc,KAAA,GAEhB,YAAY,YAAY,YAAY,YAAY,GAAG,YAAY,UAAU,GAAG,cAAc;CAG5F,IAAI,UAAU,KAAA,GACZ,YAAY,QAAQ,YAAY,QAAQ;EAAE,GAAI,YAAY;EAAyB,GAAG;CAAM,IAAI;CAGlG,IAAI,WAAW,MAAM,GAAG;EAEtB,MAAM,YAAY,YAAY,KAAK,YAAY,GAAG;EAClD,OAAO,OAAO;GAAE,GAAG;GAAa,KAAK;EAAU,GAAgB,KAAK;CACtE;CAEA,IAAI,eAAe,MAAM,GAAG;EAC1B,MAAM,aAAa,cAAc,MAAM;EAEvC,MAAM,YAAY,YAAY,KAAK,YAAY,KAAK,UAAU;EAE9D,MAAM,eAAe,WAAW,aAAa,OAAO,KAAgC;EACpF,aAAa,MAAM;EAEnB,OAAO,aAAa,QAAQ,YAAY;CAC1C;CAIA,YAAY,MADM,YAAY,KAAK,YAAY,GACrB;CAE1B,OAAO,cAAc,SAAS,WAAW;AAC3C"}
+{"version":3,"file":"use-render.js","names":[],"sources":["../../../src/utils/use-render.tsx"],"sourcesContent":["import { getStateDataAttrs, type StateAttrMap } from '@videojs/core/dom';\nimport { isFunction } from '@videojs/utils/predicate';\nimport { resolveClassName } from '@videojs/utils/style';\nimport type { CSSProperties, ReactElement, Ref } from 'react';\nimport { cloneElement, createElement, isValidElement } from 'react';\nimport { mergeProps } from './merge-props';\nimport type { HTMLProps, RenderProp } from './types';\nimport { composeRefs } from './use-composed-refs';\n\n/** Check if a value is a render prop (function or React element). */\nexport function isRenderProp(value: unknown): value is RenderProp<unknown> {\n  return isFunction(value) || isValidElement(value);\n}\n\ntype IntrinsicTagName = keyof React.JSX.IntrinsicElements;\n\nexport interface UseRenderComponentProps<State> {\n  className?: string | ((state: State) => string | undefined) | undefined;\n  style?: CSSProperties | ((state: State) => CSSProperties | undefined) | undefined;\n  render?: RenderProp<State> | undefined;\n}\n\nexport interface UseRenderParameters<State, RenderedElementType extends Element> {\n  state: State;\n  ref?: Ref<RenderedElementType> | Ref<RenderedElementType>[] | undefined;\n  props?: object | object[] | undefined;\n  stateAttrMap?: StateAttrMap<State> | undefined;\n}\n\nfunction resolveStyle<State>(\n  style: CSSProperties | ((state: State) => CSSProperties | undefined) | undefined,\n  state: State\n): CSSProperties | undefined {\n  return isFunction(style) ? style(state) : style;\n}\n\nfunction getElementRef(element: ReactElement): Ref<unknown> | undefined {\n  // React 19+ uses element.props.ref, older versions use element.ref\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const elementAny = element as any;\n  return elementAny.ref ?? elementAny.props?.ref;\n}\n\n/**\n * Render a UI component element.\n *\n * Handles:\n * - Default tag rendering\n * - Render prop (element or function)\n * - Props merging (event handlers chained, className concatenated, style merged)\n * - Ref composition\n * - className/style as functions of state\n *\n * @public\n * @example\n * ```tsx\n * return renderElement('button', componentProps, {\n *   state,\n *   ref: [forwardedRef, buttonRef],\n *   props: [{ type: 'button' }, elementProps, getButtonProps],\n * });\n * ```\n */\nexport function renderElement<\n  State extends object,\n  RenderedElementType extends Element,\n  TagName extends IntrinsicTagName,\n>(\n  element: TagName,\n  componentProps: UseRenderComponentProps<State>,\n  params: UseRenderParameters<State, RenderedElementType>\n): ReactElement | null {\n  const { className: classNameProp, style: styleProp, render } = componentProps;\n  const { state, ref, props, stateAttrMap } = params;\n\n  // Resolve className and style if they're functions\n  const className = resolveClassName(classNameProp, state);\n  const style = resolveStyle(styleProp, state);\n\n  // Generate data attributes only when a component explicitly opts in with a\n  // mapping. State is still passed to render/className/style callbacks.\n  const stateDataAttrs = stateAttrMap ? getStateDataAttrs(state, stateAttrMap) : {};\n\n  // Merge: state data attrs first, then props (so props can override)\n  const propsArray = Array.isArray(props) ? props : props ? [props] : [];\n  const mergedProps = mergeProps(stateDataAttrs, ...(propsArray as Record<string, unknown>[]));\n\n  if (className !== undefined) {\n    // Add resolved className and style\n    mergedProps.className = mergedProps.className ? `${mergedProps.className} ${className}` : className;\n  }\n\n  if (style !== undefined) {\n    mergedProps.style = mergedProps.style ? { ...(mergedProps.style as CSSProperties), ...style } : style;\n  }\n\n  if (isFunction(render)) {\n    // Render function: call with props and state\n    const mergedRef = composeRefs(ref, mergedProps.ref);\n    return render({ ...mergedProps, ref: mergedRef } as HTMLProps, state);\n  }\n\n  if (isValidElement(render)) {\n    const elementRef = getElementRef(render);\n\n    const mergedRef = composeRefs(ref, mergedProps.ref, elementRef);\n\n    const elementProps = mergeProps(mergedProps, render.props as Record<string, unknown>);\n    elementProps.ref = mergedRef;\n\n    return cloneElement(render, elementProps);\n  }\n\n  // Default tag\n  const mergedRef = composeRefs(ref, mergedProps.ref);\n  mergedProps.ref = mergedRef;\n\n  return createElement(element, mergedProps);\n}\n\nexport namespace renderElement {\n  export type ComponentProps<State> = UseRenderComponentProps<State>;\n  export type Parameters<State, RenderedElementType extends Element> = UseRenderParameters<State, RenderedElementType>;\n}\n"],"mappings":";;;;;;;AA6BA,SAAS,aACP,OACA,OAC2B;CAC3B,OAAO,WAAW,KAAK,IAAI,MAAM,KAAK,IAAI;AAC5C;AAEA,SAAS,cAAc,SAAiD;CAGtE,MAAM,aAAa;CACnB,OAAO,WAAW,OAAO,WAAW,OAAO;AAC7C;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,cAKd,SACA,gBACA,QACqB;CACrB,MAAM,EAAE,WAAW,eAAe,OAAO,WAAW,WAAW;CAC/D,MAAM,EAAE,OAAO,KAAK,OAAO,iBAAiB;CAG5C,MAAM,YAAY,iBAAiB,eAAe,KAAK;CACvD,MAAM,QAAQ,aAAa,WAAW,KAAK;CAQ3C,MAAM,cAAc,WAJG,eAAe,kBAAkB,OAAO,YAAY,IAAI,CAAC,GAIjC,GAD5B,MAAM,QAAQ,KAAK,IAAI,QAAQ,QAAQ,CAAC,KAAK,IAAI,CAAC,CACsB;CAE3F,IAAI,cAAc,KAAA,GAEhB,YAAY,YAAY,YAAY,YAAY,GAAG,YAAY,UAAU,GAAG,cAAc;CAG5F,IAAI,UAAU,KAAA,GACZ,YAAY,QAAQ,YAAY,QAAQ;EAAE,GAAI,YAAY;EAAyB,GAAG;CAAM,IAAI;CAGlG,IAAI,WAAW,MAAM,GAAG;EAEtB,MAAM,YAAY,YAAY,KAAK,YAAY,GAAG;EAClD,OAAO,OAAO;GAAE,GAAG;GAAa,KAAK;EAAU,GAAgB,KAAK;CACtE;CAEA,IAAI,eAAe,MAAM,GAAG;EAC1B,MAAM,aAAa,cAAc,MAAM;EAEvC,MAAM,YAAY,YAAY,KAAK,YAAY,KAAK,UAAU;EAE9D,MAAM,eAAe,WAAW,aAAa,OAAO,KAAgC;EACpF,aAAa,MAAM;EAEnB,OAAO,aAAa,QAAQ,YAAY;CAC1C;CAIA,YAAY,MADM,YAAY,KAAK,YAAY,GACrB;CAE1B,OAAO,cAAc,SAAS,WAAW;AAC3C"}

package/dist/dev/utils/use-safe-id.js

@@ -1,4 +1,3 @@
-"use client";
 import { useId } from "react";
 //#region src/utils/use-safe-id.ts
 const UNSAFE_CHARS = /[^a-zA-Z0-9_-]/g;

package/dist/dev/utils/use-safe-id.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-safe-id.js","names":[],"sources":["../../../src/utils/use-safe-id.ts"],"sourcesContent":["'use client';\n\nimport { useId } from 'react';\n\nconst UNSAFE_CHARS = /[^a-zA-Z0-9_-]/g;\n\n/**\n * Generate a CSS-safe identifier from React's `useId()`.\n *\n * `useId()` returns values like `:r0:` which contain colons — invalid\n * in CSS `<dashed-ident>` tokens (used by `anchor-name` / `position-anchor`).\n * This hook strips non-alphanumeric/underscore/hyphen characters and\n * optionally prepends a prefix.\n */\nexport function useSafeId(prefix?: string): string {\n  const raw = useId().replace(UNSAFE_CHARS, '');\n  return prefix ? `${prefix}-${raw}` : raw;\n}\n"],"mappings":";;;AAIA,MAAM,eAAe;;;;;;;;;AAUrB,SAAgB,UAAU,QAAyB;CACjD,MAAM,MAAM,MAAM,CAAC,CAAC,QAAQ,cAAc,EAAE;CAC5C,OAAO,SAAS,GAAG,OAAO,GAAG,QAAQ;AACvC"}
+{"version":3,"file":"use-safe-id.js","names":[],"sources":["../../../src/utils/use-safe-id.ts"],"sourcesContent":["import { useId } from 'react';\n\nconst UNSAFE_CHARS = /[^a-zA-Z0-9_-]/g;\n\n/**\n * Generate a CSS-safe identifier from React's `useId()`.\n *\n * `useId()` returns values like `:r0:` which contain colons — invalid\n * in CSS `<dashed-ident>` tokens (used by `anchor-name` / `position-anchor`).\n * This hook strips non-alphanumeric/underscore/hyphen characters and\n * optionally prepends a prefix.\n */\nexport function useSafeId(prefix?: string): string {\n  const raw = useId().replace(UNSAFE_CHARS, '');\n  return prefix ? `${prefix}-${raw}` : raw;\n}\n"],"mappings":";;AAEA,MAAM,eAAe;;;;;;;;;AAUrB,SAAgB,UAAU,QAAyB;CACjD,MAAM,MAAM,MAAM,CAAC,CAAC,QAAQ,cAAc,EAAE;CAC5C,OAAO,SAAS,GAAG,OAAO,GAAG,QAAQ;AACvC"}

package/docs/README.md

@@ -1,6 +1,6 @@
 # @videojs/react documentation
 
-Bundled markdown documentation for `@videojs/react` v10.0.0-beta.27.
+Bundled markdown documentation for `@videojs/react` v10.0.0-beta.29.
 
 Start at [`./llms.txt`](./llms.txt) — it's the structured index of every page in this directory.
 

package/docs/concepts/features.md

@@ -91,7 +91,7 @@ playback?.play();
 
 ### Checking for feature support
 
-Volume, fullscreen, and picture-in-picture expose an `*Availability` property because platform support varies. For example, iOS Safari doesn’t allow programmatic volume control.
+Volume, fullscreen, and picture-in-picture expose availability properties because platform support varies. Volume has two independent properties: `volumeAvailability` for changing the volume level and `mutedAvailability` for toggling mute. For example, iOS Safari allows muting but doesn’t allow programmatic volume control.
 
 Value
 
@@ -109,7 +109,7 @@ Could work, not ready yet
 
 Platform can never do this
 
-Components that depend on availability (like [`PiPButton`](../reference/pip-button.md) and [`FullscreenButton`](../reference/fullscreen-button.md)) handle the three states for you:
+Components that depend on availability (like [`MuteButton`](../reference/mute-button.md), [`PiPButton`](../reference/pip-button.md), and [`FullscreenButton`](../reference/fullscreen-button.md)) handle the three states for you:
 
 *   **`unsupported`** — the HTML custom element receives the native `hidden` attribute (and `data-hidden`); React buttons return `null`. No CSS needed.
 *   **`unavailable`** — the presentation controls stay hidden while capability detection is unresolved. Cast remains visible but disabled when its API is supported and no device is reachable.

package/docs/concepts/media-sources.md

@@ -42,7 +42,7 @@ How Video.js plays it
 
 `source`, at the top level
 
-`preferPlayback`
+`preferPlayback`, `maxAutoResolution`, `capRenditionToPlayerSize`
 
 How a specific engine behaves
 
@@ -192,6 +192,80 @@ tsx
 
 It’s a preference, not a demand — Video.js falls back to whichever path can actually play the source. `HlsJsVideo`, `MuxVideo`, and `MuxAudio` accept it; DASH and Vimeo have no second playback path.
 
+`maxAutoResolution` caps the highest rendition adaptive bitrate selection reaches for on its own:
+
+tsx
+
+```
+<HlsJsVideo source={{ src: 'https://example.com/stream.m3u8', maxAutoResolution: '720p' }} />
+```
+
+The cap limits automatic selection without hiding anything. Renditions above it stay in `videoRenditions`, so a viewer can still choose 1080p by hand. Reach for it to hold down bandwidth on a stream that would otherwise climb to 4K, or to keep a background or thumbnail player cheap.
+
+Renditions are matched on pixel area rather than height, which keeps unusual aspect ratios honest: an ultrawide 2560×1080 rendition carries more pixels than 16:9 1080p, so a `'1080p'` cap leaves it out. When every rendition sits above the cap, the smallest one plays.
+
+Changing the cap applies to the running engine, so playback continues uninterrupted. It needs the hls.js engine — native HLS playback ignores it, and audio-only streams have no video renditions to cap.
+
+### Capping to the player’s size
+
+A 400px-wide player has no use for a 4K rendition, so `capRenditionToPlayerSize` holds automatic selection to the smallest rendition that still covers the element. It defaults to `true`, and the cap follows the element as it’s resized:
+
+tsx
+
+```
+<HlsJsVideo source={{ src: 'https://example.com/stream.m3u8', capRenditionToPlayerSize: false }} />
+```
+
+The element is measured in device pixels, so a `2` device pixel ratio asks for twice the rendition a CSS measurement would — a 640px-wide player on a retina screen still gets 720p. Switch the cap off for a player whose layout size understates what it needs, such as one that goes fullscreen without a resize.
+
+`minAutoResolution` bounds how far down that cap can reach, and defaults to `'720p'`:
+
+tsx
+
+```
+<HlsJsVideo source={{ src: 'https://example.com/stream.m3u8', minAutoResolution: '480p' }} />
+```
+
+**It is not a quality floor.** It bounds the size-derived cap and nothing else. When bandwidth is poor, adaptive selection still drops below it — the cap is a ceiling, and selection stays free underneath. It also never raises an explicit `maxAutoResolution`: ask for at most `'360p'` alongside a `'720p'` floor and you get `'360p'`.
+
+The default is there because the low rungs of a ladder exist for poor network conditions, and capping a small player down to them looks worse than its size suggests. Name a lower rung to weaken the floor, or `'270p'` to lift it for any real ladder.
+
+### Four things that sound alike
+
+Four separate mechanisms bound which rendition plays, and they’re easy to mistake for each other:
+
+Option
+
+Side
+
+What it does
+
+`source.playback.maxResolution`
+
+Server
+
+A Mux query param. Trims the manifest, so higher renditions never arrive — not even by hand.
+
+`source.maxAutoResolution`
+
+Client
+
+A ceiling on automatic selection. Everything still arrives and stays selectable by hand.
+
+`source.capRenditionToPlayerSize`
+
+Client
+
+The same kind of ceiling, derived from the element’s rendered size and moving with it.
+
+`source.minAutoResolution`
+
+Client
+
+A bound on the one above. Not a quality minimum, and not related to `playback.minResolution`.
+
+`playback.maxResolution` and `playback.minResolution` are the server-side pair: they decide what the manifest carries. The other three only bound what adaptive selection picks from whatever does arrive.
+
 ## DRM protected sources
 
 Protected content is licensed through `source.drm`, keyed by EME key system id — alongside the URL rather than inside an engine’s namespace, because which engine plays the manifest is decided later and both paths read it:
@@ -265,6 +339,10 @@ tsx
 />
 ```
 
+`playback` params ride along in the URL, so `playback.maxResolution` decides which renditions the manifest carries in the first place. `maxAutoResolution` is the other half of that pair: it caps what adaptive selection picks from the renditions that do arrive. Use `playback.maxResolution` when a viewer should never get 4K, and `maxAutoResolution` when they should be able to ask for it.
+
+The same split applies at the bottom of the ladder, and the names are close enough to be worth restating: `playback.minResolution` asks Mux to leave the lowest renditions out of the manifest, while `minAutoResolution` is a client-side bound on the player-size cap. They are unrelated.
+
 Setting a Mux stream URL as `src` works too — the element parses the playback ID and query params back out into `source`. To play something Mux doesn’t host, name it with `src` inside `source`; engine options still apply.
 
 Two more source params describe images rather than playback. `source.storyboard` and `source.poster` carry the modifiers for the storyboard VTT and the poster still — both belong to the source, since a signed token scopes them to one playback ID:

package/docs/concepts/skins.md

@@ -64,10 +64,10 @@ skin.css
 ```
 'use client';
 
-import { type CSSProperties, type ComponentProps, forwardRef, type ReactNode, isValidElement } from 'react';
+import { type CSSProperties, type ComponentProps, forwardRef, type ReactNode } from 'react';
 import { audioText, captionsText, playbackRateText, qualityText, settingsText, speedText } from '@videojs/core/i18n/text/menu';
 import { AirPlayEnterIcon, AirPlayExitIcon, CaptionsOffIcon, CaptionsOnIcon, CastEnterIcon, CastExitIcon, CheckIcon, ChevronIcon, FullscreenEnterIcon, FullscreenExitIcon, GearIcon, PauseIcon, PipEnterIcon, PipExitIcon, PlayIcon, QualityIcon, RestartIcon, SpeechIcon, SpeedIcon, SpinnerIcon, VolumeHighIcon, VolumeLowIcon, VolumeOffIcon } from '@videojs/react/icons';
-import { Poster, useTranslator, Container, usePlayer, AirPlayButton, useAudioTrackOptions, AudioTrackRadioGroup, BufferingIndicator, CaptionsButton, CaptionsRadioGroup, useCaptionsOptions, CastButton, Controls, ErrorDialog, FullscreenButton, Gesture, Hotkey, Menu, MuteButton, PiPButton, PlayButton, usePlaybackRateOptions, PlaybackRateRadioGroup, Popover, useQualityOptions, QualityRadioGroup, SeekIndicator, Slider, StatusAnnouncer, StatusIndicator, Time, TimeSlider, Tooltip, VolumeIndicator, VolumeSlider, type RenderProp } from '@videojs/react';
+import { Poster, useTranslator, Container, usePlayer, AirPlayButton, useAudioTrackOptions, AudioTrackRadioGroup, BufferingIndicator, CaptionsButton, CaptionsRadioGroup, useCaptionsOptions, CastButton, Controls, ErrorDialog, FullscreenButton, Gesture, Hotkey, Menu, MuteButton, PiPButton, PlayButton, usePlaybackRateOptions, PlaybackRateRadioGroup, Popover, useQualityOptions, QualityRadioGroup, SeekIndicator, Slider, StatusAnnouncer, StatusIndicator, Time, TimeSlider, Tooltip, VolumeIndicator, VolumeSlider } from '@videojs/react';
 import { Video } from '@videojs/react/video';
 import './player.css';
 import { Player } from './player';
@@ -350,9 +350,11 @@ const SEEK_TIME = 10;
 
 export interface VideoPlayerProps {
   src: string;
+  poster?: string | undefined;
   style?: CSSProperties;
   className?: string;
-  poster?: string | RenderProp<Poster.State> | undefined;
+  renderPoster?: Poster.Props['render'];
+  placeholder?: string | undefined;
 }
 
 /**
@@ -364,13 +366,13 @@ export interface VideoPlayerProps {
  * />
  * ```
  */
-export function VideoPlayer({ src, className, poster, placeholder, style, ...rest }: VideoPlayerProps): ReactNode {
+export function VideoPlayer({ src, poster, className, renderPoster, placeholder, style, ...rest }: VideoPlayerProps): ReactNode {
   const containerStyle = placeholder
     ? ({ '--media-poster-placeholder': `url(${placeholder})`, ...style } as CSSProperties)
     : style;
 
   return (
-    <Player>
+    <Player poster={poster}>
       <Container
         className={`media-default-skin media-default-skin--video ${className ?? ''}`}
         style={containerStyle}
@@ -378,9 +380,7 @@ export function VideoPlayer({ src, className, poster, placeholder, style, ...res
       >
         <Video src={src} playsInline />
 
-        {poster && (
-          <Poster src={isString(poster) ? poster : undefined} render={isRenderProp(poster) ? poster : undefined} />
-        )}
+        <Poster render={renderPoster} />
 
         <BufferingIndicator
           render={(props) => (
@@ -604,18 +604,6 @@ function VolumePopover(): ReactNode {
     </Popover.Root>
   );
 }
-
-// ================================================================
-// Utilities
-// ================================================================
-
-function isString(value: unknown): value is string {
-  return typeof value === 'string';
-}
-
-function isRenderProp(value: unknown): value is RenderProp<unknown> {
-  return typeof value === 'function' || isValidElement(value);
-}
 ```
 ```
 import { createPlayer } from '@videojs/react';
@@ -1183,7 +1171,7 @@ export const { Player } = createPlayer({ features: videoFeatures });
     position: relative;
     display: block;
     max-width: var(--thumbnail-max-width);
-    max-height: var(--max-height);
+    max-height: var(--thumbnail-max-height);
     overflow: clip;
     border-radius: inherit;
 
@@ -1235,9 +1223,13 @@ export const { Player } = createPlayer({ features: videoFeatures });
 }
 
 .media-default-skin .media-slider {
-  --thumb-size: calc(var(--spacing) * 2.5);
-  --thumb-active-size: calc(var(--spacing) * 3);
-  --track-border-radius: calc(Infinity * 1px);
+  --track-size: calc(var(--spacing) * 1);
+  --track-highlighted-size: calc(var(--spacing) * 1.75);
+  --track-border-radius: 99px;
+  --thumb-size: calc(var(--spacing) * 3);
+  --chapter-gap: calc(var(--spacing) * 1);
+  --chapter-inset-start: calc(var(--chapter-gap) / 2);
+  --chapter-inset-end: calc(var(--chapter-gap) / 2);
 
   position: relative;
   display: flex;
@@ -1268,10 +1260,10 @@ export const { Player } = createPlayer({ features: videoFeatures });
 
     &[data-orientation="horizontal"] {
       width: 100%;
-      height: calc(var(--spacing) * 1);
+      height: var(--track-size);
     }
     &[data-orientation="vertical"] {
-      width: calc(var(--spacing) * 1);
+      width: var(--track-size);
       height: 100%;
     }
   }
@@ -1287,13 +1279,22 @@ export const { Player } = createPlayer({ features: videoFeatures });
       inset-block: 0;
       left: 0;
       width: 100%;
-      transition-property: clip-path;
     }
     &[data-orientation="vertical"] {
       inset-inline: 0;
       bottom: 0;
       height: 100%;
-      transition-property: clip-path;
+    }
+
+    @media (prefers-reduced-motion: no-preference) {
+      transition: clip-path 200ms ease-out;
+    }
+  }
+  &[data-dragging],
+  &[data-seeking] {
+    .media-slider__fill,
+    .media-slider__buffer {
+      transition-duration: 0ms;
     }
   }
 
@@ -1320,6 +1321,14 @@ export const { Player } = createPlayer({ features: videoFeatures });
       clip-path: inset(calc(100% - var(--media-slider-fill)) 0 0 0 round var(--track-border-radius));
     }
   }
+  &[data-dragging] {
+    .media-slider__fill[data-orientation="horizontal"] {
+      clip-path: inset(0 calc(100% - var(--media-slider-pointer)) 0 0 round var(--track-border-radius));
+    }
+    .media-slider__fill[data-orientation="vertical"] {
+      clip-path: inset(calc(100% - var(--media-slider-pointer)) 0 0 0 round var(--track-border-radius));
+    }
+  }
 
   /* Chapters */
   .media-slider__chapters {
@@ -1343,10 +1352,6 @@ export const { Player } = createPlayer({ features: videoFeatures });
   }
 
   .media-slider__chapter {
-    --chapter-gap: calc(var(--spacing) * 1);
-    --chapter-inset-start: 0.5;
-    --chapter-inset-end: 0.5;
-
     position: absolute;
     inset: 0;
     display: flex;
@@ -1357,16 +1362,13 @@ export const { Player } = createPlayer({ features: videoFeatures });
     border-radius: inherit;
 
     &:first-child {
-      --chapter-inset-start: 0;
+      --chapter-inset-start: 0px;
     }
     &:last-child {
-      --chapter-inset-end: 0;
+      --chapter-inset-end: 0px;
     }
 
     .media-slider__chapter-track {
-      --chapter-track-size: calc(var(--spacing) * 1);
-      --chapter-track-highlighted-size: calc(var(--spacing) * 1.75);
-
       border-radius: inherit;
 
       @media (prefers-reduced-motion: no-preference) {
@@ -1379,16 +1381,15 @@ export const { Player } = createPlayer({ features: videoFeatures });
       clip-path: inset(0 calc(100% - var(--media-slider-chapter-end)) 0 var(--media-slider-chapter-start));
 
       .media-slider__chapter-track {
-        height: var(--chapter-track-size);
+        height: var(--track-size);
         clip-path: inset(
-          0 calc(100% - var(--media-slider-chapter-end) + var(--chapter-gap) * var(--chapter-inset-end)) 0
-            calc(var(--media-slider-chapter-start) + var(--chapter-gap) * var(--chapter-inset-start)) round
-            var(--track-border-radius)
+          0 calc(100% - var(--media-slider-chapter-end) + var(--chapter-inset-end)) 0
+            calc(var(--media-slider-chapter-start) + var(--chapter-inset-start)) round var(--track-border-radius)
         );
       }
 
       &[data-highlighted] .media-slider__chapter-track {
-        height: var(--chapter-track-highlighted-size);
+        height: var(--track-highlighted-size);
       }
     }
 
@@ -1396,59 +1397,19 @@ export const { Player } = createPlayer({ features: videoFeatures });
       clip-path: inset(calc(100% - var(--media-slider-chapter-end)) 0 var(--media-slider-chapter-start) 0);
 
       .media-slider__chapter-track {
-        width: var(--chapter-track-size);
+        width: var(--track-size);
         clip-path: inset(
-          calc(100% - var(--media-slider-chapter-end) + var(--chapter-gap) * var(--chapter-inset-end)) 0
-            calc(var(--media-slider-chapter-start) + var(--chapter-gap) * var(--chapter-inset-start)) 0 round
-            var(--track-border-radius)
+          calc(100% - var(--media-slider-chapter-end) + var(--chapter-inset-end)) 0
+            calc(var(--media-slider-chapter-start) + var(--chapter-inset-start)) 0 round var(--track-border-radius)
         );
       }
 
       &[data-highlighted] .media-slider__chapter-track {
-        width: var(--chapter-track-highlighted-size);
+        width: var(--track-highlighted-size);
       }
     }
   }
 
-  /* Dragging — thumb and fill follow the pointer position */
-  &[data-dragging] {
-    .media-slider__thumb[data-orientation="horizontal"] {
-      left: var(--media-slider-pointer);
-    }
-    .media-slider__thumb[data-orientation="vertical"] {
-      top: calc(100% - var(--media-slider-pointer));
-    }
-    .media-slider__fill[data-orientation="horizontal"] {
-      clip-path: inset(0 calc(100% - var(--media-slider-pointer)) 0 0 round var(--track-border-radius));
-    }
-    .media-slider__fill[data-orientation="vertical"] {
-      clip-path: inset(calc(100% - var(--media-slider-pointer)) 0 0 0 round var(--track-border-radius));
-    }
-  }
-
-  @media (prefers-reduced-motion: no-preference) {
-    .media-slider__thumb {
-      transition-property: opacity, height, width, outline-offset, left, top;
-    }
-    .media-slider__fill {
-      transition-timing-function: linear;
-      transition-duration: 200ms;
-    }
-    .media-slider__buffer {
-      transition-timing-function: ease-out;
-      transition-duration: 250ms;
-    }
-  }
-
-  &[data-dragging],
-  &[data-seeking] {
-    .media-slider__thumb,
-    .media-slider__fill,
-    .media-slider__buffer {
-      transition-duration: 0ms;
-    }
-  }
-
   /* Thumb */
   .media-slider__thumb {
     position: absolute;
@@ -1465,10 +1426,8 @@ export const { Player } = createPlayer({ features: videoFeatures });
       0 1px 3px 0 oklch(0 0 0 / 0.35),
       0 1px 2px -1px oklch(0 0 0 / 0.35);
     opacity: 0;
+    scale: 0.8;
     translate: -50% -50%;
-    transition-timing-function: ease-out;
-    transition-duration: 150ms;
-    transition-property: opacity, height, width, outline-offset;
 
     &[data-orientation="horizontal"] {
       top: 50%;
@@ -1485,22 +1444,12 @@ export const { Player } = createPlayer({ features: videoFeatures });
       opacity: 1;
     }
 
-    @media (hover: hover) and (pointer: fine) {
-      &:hover {
-        outline-color: oklch(from currentColor l c h / 0.15);
-        outline-offset: 0;
-      }
-    }
-
     &::after {
       position: absolute;
       inset: -4px;
       content: "";
       border-radius: inherit;
       box-shadow: 0 0 0 2px currentColor;
-      transition-timing-function: ease-out;
-      transition-duration: 150ms;
-      transition-property: opacity, scale;
     }
 
     &:not(:focus-visible)::after {
@@ -1509,37 +1458,70 @@ export const { Player } = createPlayer({ features: videoFeatures });
     }
 
     &.media-slider__thumb--persistent {
-      width: var(--thumb-active-size);
-      height: var(--thumb-active-size);
       opacity: 1;
+      scale: 1;
     }
-  }
 
-  &:active .media-slider__thumb,
-  &:focus-within .media-slider__thumb {
-    width: var(--thumb-active-size);
-    height: var(--thumb-active-size);
+    @media (hover: hover) and (pointer: fine) {
+      &:hover {
+        outline-color: oklch(from currentColor l c h / 0.15);
+        outline-offset: 0;
+      }
+    }
+
+    @media (prefers-reduced-motion: no-preference) {
+      transition-timing-function: ease-out;
+      transition-duration: 150ms;
+      transition-property: opacity, outline-offset, left, top, scale;
+
+      &::after {
+        transition-timing-function: ease-out;
+        transition-duration: 150ms;
+        transition-property: opacity, scale;
+      }
+    }
   }
 
   @media (hover: hover) and (pointer: fine) {
     &:hover .media-slider__thumb {
       opacity: 1;
+      scale: 1;
+    }
+  }
+
+  &[data-dragging] .media-slider__thumb {
+    opacity: 1;
+    scale: 0.9;
+
+    @media (prefers-reduced-motion: no-preference) {
+      transition-property: opacity, outline-offset, scale;
+    }
+
+    &[data-orientation="horizontal"] {
+      left: var(--media-slider-pointer);
+    }
+    &[data-orientation="vertical"] {
+      top: calc(100% - var(--media-slider-pointer));
     }
   }
 
   /* Preview */
   .media-slider__preview {
-    --max-width: min(calc(var(--spacing) * 48), 100cqi);
-    --max-height: calc(var(--spacing) * 32);
+    --max-size-factor: 36;
+    --max-size: min(calc(var(--spacing) * var(--max-size-factor)), 100cqi);
 
-    min-width: var(--max-width);
+    min-width: var(--max-size);
     height: calc(var(--spacing) * 1);
 
+    @container media-root (width > 42rem) {
+      --max-size-factor: 48;
+    }
+
     .media-slider__thumbnail,
     .media-slider__value {
       position: absolute;
       left: 50%;
-      max-width: var(--max-width);
+      max-width: var(--max-size);
       opacity: 0;
       filter: blur(8px);
       transform-origin: bottom;
@@ -1550,7 +1532,8 @@ export const { Player } = createPlayer({ features: videoFeatures });
     }
 
     .media-slider__thumbnail {
-      --thumbnail-max-width: var(--max-width);
+      --thumbnail-max-width: var(--max-size);
+      --thumbnail-max-height: var(--max-size);
       bottom: calc(100% + (var(--spacing) * 9));
     }
 
@@ -1564,8 +1547,8 @@ export const { Player } = createPlayer({ features: videoFeatures });
 
     .media-slider__chapter-title {
       min-width: 0;
-      max-width: var(--max-width);
-      padding-inline: calc(var(--spacing) * 3);
+      max-width: var(--max-size);
+      padding-inline: calc(var(--spacing) * 6);
       overflow: hidden;
       text-overflow: ellipsis;
       white-space: nowrap;
@@ -1596,14 +1579,15 @@ export const { Player } = createPlayer({ features: videoFeatures });
       transition-duration: 200ms;
       transition-property: opacity, scale;
     }
+  }
 
-    &[data-pointing]:not([data-dragging])::before,
-    &[data-pointing] :is(.media-slider__thumbnail, .media-slider__value),
-    &[data-interactive]:not([data-pointing]):not([data-dragging]) :is(.media-slider__value, .media-slider__thumbnail) {
-      opacity: 1;
-      filter: blur(0);
-      scale: 1;
-    }
+  &:is([data-pointing], :has(:focus-visible))
+    .media-slider__preview
+    :is(.media-slider__value, .media-slider__thumbnail),
+  .media-slider__preview[data-pointing]:not([data-dragging])::before {
+    opacity: 1;
+    filter: blur(0);
+    scale: 1;
   }
 }
 
@@ -2310,8 +2294,8 @@ export const { Player } = createPlayer({ features: videoFeatures });
    still in the DOM — just `display: none` — so its animations would keep
    running. Set the variables to `none` to short-circuit the keyframes. */
 .media-button--airplay:not([data-airplay-state="connected"]) {
-  --media-icon--airplay__fill-animation: none;
-  --media-icon--airplay__triangle-animation: none;
+  --media-icon-airplay-fill-animation: none;
+  --media-icon-airplay-triangle-animation: none;
 }
 
 @media (prefers-reduced-motion: reduce) {
@@ -2407,6 +2391,10 @@ export const { Player } = createPlayer({ features: videoFeatures });
       --scale: 1.75;
     }
   }
+
+  * {
+    --focus-ring-color: oklch(1 0 0);
+  }
 }
 
 /* Error Dialog  */
@@ -2474,6 +2462,12 @@ export const { Player } = createPlayer({ features: videoFeatures });
   .media-controls--primary,
   .media-controls--secondary {
     position: absolute;
+  }
+  /* Primary must be higher for the preview/thumbnail */
+  .media-controls--primary {
+    z-index: 20;
+  }
+  .media-controls--secondary {
     z-index: 10;
   }
 
@@ -2490,6 +2484,11 @@ export const { Player } = createPlayer({ features: videoFeatures });
     transform-origin: top;
   }
 
+  .media-time-controls {
+    flex: 1;
+    padding-inline: calc(var(--spacing) * 2);
+  }
+
   @container media-root (width < 32rem) {
     .media-controls--primary,
     .media-controls--secondary {
@@ -2540,6 +2539,10 @@ export const { Player } = createPlayer({ features: videoFeatures });
         }
       }
     }
+
+    .media-button--captions {
+      display: none;
+    }
   }
 
   @container media-root (width >= 32rem) {
@@ -2576,11 +2579,10 @@ export const { Player } = createPlayer({ features: videoFeatures });
         translate: 0 4px;
       }
     }
-  }
 
-  .media-time-controls {
-    flex: 1;
-    padding-inline: calc(var(--spacing) * 3);
+    .media-time-controls {
+      padding-inline: calc(var(--spacing) * 3);
+    }
   }
 
   @media (pointer: fine) {

package/docs/how-to/build-your-own-component.md

@@ -50,7 +50,7 @@ Feature
 
 Browse the full list in the **Features** section of the sidebar.
 
-Each feature also has an **availability** property (`'available'`, `'unavailable'`, or `'unsupported'`) for hiding controls the platform does not support. See [Features](../concepts/features.md) for details.
+Features for platform-dependent capabilities also expose one or more **availability** properties (`'available'`, `'unavailable'`, or `'unsupported'`) for hiding controls the platform does not support. See [Features](../concepts/features.md) for details.
 
 Access state and actions with [`usePlayer`](../reference/use-player.md):