@videojs/react 10.0.0-rc.1 → 10.0.0-rc.3

package/docs/how-to/add-a-poster-and-loading-placeholder.md

@@ -1,232 +0,0 @@
-# Add a poster and loading placeholder
-
-Set the image shown before playback, then add a lightweight placeholder while it loads
-
-A poster is the image shown before your video plays. There are several places to set one, so work down this list and stop at the first step that fits:
-
-1.  **Let the media provide it.** Some media components create a poster from the source, so there is nothing extra to host or keep in sync.
-2.  **Set `poster` on the player.** With a packaged skin, that is all a static image needs.
-3.  **Take control of the image** when you need a framework image component, a `<picture>` element, or a loading placeholder. The skin renders your image instead of its own.
-4.  **Keep it working in an [ejected skin](./customize-skins.md#eject-and-edit-a-skin).** The player’s `poster` still reaches the Poster component your skin renders, or you can set the image’s source yourself.
-
-## Let the media provide a poster
-
-Some media components choose a poster for you. For example, `MuxVideo` creates one from its playback ID:
-
-Install the React façade and the Mux playback adapter:
-
-bash
-
-```
-pnpm add @videojs/react @videojs/mux-video
-```
-
-tsx
-
-```
-import '@videojs/react/video/skin.css';
-import { MuxVideo } from '@videojs/react/media/mux-video';
-import { VideoPlayer, VideoSkin } from '@videojs/react/video';
-
-export function MyPlayer() {
-  return (
-    <VideoPlayer>
-      <VideoSkin>
-        <MuxVideo
-          source={{
-            playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
-            poster: { time: 2 },
-          }}
-          playsInline
-        />
-      </VideoSkin>
-    </VideoPlayer>
-  );
-}
-```
-
-## Set a poster on the player
-
-When the media has no poster of its own, set the player’s `poster` to an image URL:
-
-tsx
-
-```
-import '@videojs/react/video/skin.css';
-import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
-
-export function MyPlayer() {
-  return (
-    <VideoPlayer poster="/poster.jpg">
-      <VideoSkin>
-        <Video src="/video.mp4" playsInline />
-      </VideoSkin>
-    </VideoPlayer>
-  );
-}
-```
-
-If you use a ready-made skin, it includes [Poster](../reference/poster.md) and shows the image automatically. If you build your own UI, add Poster yourself. It hides after the user plays or seeks.
-
-When the player and the media component both choose a poster, the player’s `poster` wins. See [Metadata](../reference/feature-metadata.md) for how the player combines those values.
-
-Posters are decorative by default, with an empty `alt`. If the image communicates something that is not available elsewhere, add `alt` text when you customize the poster image.
-
-## Take control of the poster image
-
-The packaged skins also accept an image of your own, for when a plain `<img>` is not enough:
-
-Pass `renderPoster` to the skin. Video.js passes the poster URL as `src` alongside the rest of the image props; `src` stays `undefined` until a poster URL resolves. That fits a framework image component:
-
-tsx
-
-```
-import '@videojs/react/video/skin.css';
-import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
-import NextImage from 'next/image';
-
-export function MyPlayer() {
-  return (
-    <VideoPlayer poster="/poster.jpg">
-      <VideoSkin
-        renderPoster={({ src, ...props }) =>
-          src ? <NextImage {...props} src={src} alt="" fill /> : null
-        }
-      >
-        <Video src="/video.mp4" playsInline />
-      </VideoSkin>
-    </VideoPlayer>
-  );
-}
-```
-
-## Add a loading placeholder
-
-A placeholder is a tiny preview that appears while the poster downloads, so a slow poster does not leave the player as empty space. Keep it small enough to include with the page, such as a short data URL. Add it to the customized image from the previous section.
-
-### Use your framework’s image component
-
-If your image component supports placeholders, pass yours through `renderPoster`:
-
-tsx
-
-```
-import '@videojs/react/video/skin.css';
-import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
-import NextImage from 'next/image';
-
-export function MyPlayer() {
-  return (
-    <VideoPlayer poster="/poster.jpg">
-      <VideoSkin
-        renderPoster={({ src, ...props }) =>
-          src ? (
-            <NextImage
-              {...props}
-              src={src}
-              alt=""
-              fill
-              placeholder="blur"
-              blurDataURL="data:image/webp;base64,…"
-            />
-          ) : null
-        }
-      >
-        <Video src="/video.mp4" playsInline />
-      </VideoSkin>
-    </VideoPlayer>
-  );
-}
-```
-
-Next.js generates blur data for static imports. Here, the poster URL arrives while the player runs, so provide `blurDataURL` yourself.
-
-### Use a plain image
-
-For more control, add the placeholder as a background on the image that `VideoSkin` draws:
-
-tsx
-
-```
-import '@videojs/react/video/skin.css';
-import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
-
-export function MyPlayer() {
-  return (
-    <VideoPlayer poster="/poster.jpg">
-      <VideoSkin
-        renderPoster={(props) => (
-          <img
-            {...props}
-            style={{
-              ...props.style,
-              background:
-                "url('data:image/webp;base64,…') var(--media-object-position, center) / contain no-repeat",
-            }}
-          />
-        )}
-      >
-        <Video src="/video.mp4" playsInline />
-      </VideoSkin>
-    </VideoPlayer>
-  );
-}
-```
-
-The examples use `contain` for both images. Use `cover` for both when the poster should fill the player. Keeping the same size and position prevents the image from jumping when the poster appears.
-
-## Set the poster in an ejected skin
-
-Ejecting a skin changes nothing about the first two approaches: the player’s `poster`, or the poster the media provides, still reaches the [Poster](../reference/poster.md) component your skin renders.
-
-Poster renders an `<img>` and fills its `src` from the player, so `srcSet`, `sizes`, `loading`, and the rest of the image attributes are yours. Provide your own `src` or `srcSet` and Video.js leaves the image alone.
-
-When your UI already includes Poster, apply a placeholder through its `render` prop:
-
-tsx
-
-```
-<Poster
-  render={(props) => (
-    <img
-      {...props}
-      style={{
-        ...props.style,
-        background:
-          "url('data:image/webp;base64,…') var(--media-object-position, center) / contain no-repeat",
-      }}
-    />
-  )}
-/>
-```
-
-## Troubleshooting
-
-### No poster appears
-
-Check that the player has a `poster` or that the media component can create one from its source.
-
-### The final poster never appears
-
-Pass the `src` from `renderPoster` to your image. If your image component requires a source, return `null` until `src` is available.
-
-### The placeholder and poster use different crops
-
-Use the same fit for both images: pair `background-size: contain` with `object-fit: contain`, or use `cover` for both.
-
-### The placeholder adds too much page weight
-
-Use fewer pixels and stronger compression. The placeholder only needs to suggest the poster’s color and shape until the full image appears.
-
-## Related components
-
-*   [Poster](../reference/poster.md)
-
-## Related API
-
-*   [Metadata](../reference/feature-metadata.md)
-
-## Related guides
-
-*   [Customize skins](./customize-skins.md#style-a-packaged-skin)
-*   [Build your own UI component](./build-your-own-component.md)

package/docs/how-to/add-keyboard-shortcuts-and-gestures.md

@@ -1,97 +0,0 @@
-# Add keyboard shortcuts and gestures
-
-Add keyboard shortcuts, tap and double-tap gestures, and on-screen feedback for input actions.
-
-Add keyboard shortcuts and pointer gestures to the player declaratively, with on-screen feedback and screen-reader announcements.
-
-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
-
-Declare shortcuts with `Hotkey` and gestures with `Gesture` inside the player container. Each maps an input to a player action; the prebuilt skins ship a full set.
-
-tsx
-
-```
-import { Container, Gesture, Hotkey } from '@videojs/react';
-import { Video, VideoPlayer } from '@videojs/react/video';
-
-export default function App() {
-  return (
-    <VideoPlayer>
-      <Container>
-        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
-
-        <Hotkey keys="Space" action="togglePaused" />
-        <Hotkey keys="m" action="toggleMuted" />
-        <Hotkey keys="f" action="toggleFullscreen" />
-        <Hotkey keys="ArrowRight" action="seekStep" value={5} />
-        <Hotkey keys="ArrowLeft" action="seekStep" value={-5} />
-
-        <Gesture type="tap" action="togglePaused" pointer="mouse" region="center" />
-        <Gesture type="tap" action="toggleControls" pointer="touch" />
-        <Gesture type="doubletap" action="seekStep" value={-10} region="left" />
-        <Gesture type="doubletap" action="seekStep" value={10} region="right" />
-      </Container>
-    </VideoPlayer>
-  );
-}
-```
-
-## How it works
-
-*   `Hotkey` binds keys to player actions: `togglePaused`, `toggleMuted`, `toggleFullscreen`, `toggleSubtitles`, `togglePictureInPicture`, `seekStep`, `volumeStep`, `seekToPercent`, `speedUp`, and `speedDown`. Step actions have shared defaults and accept a custom `value`. The actions call the same feature state actions your components use.
-*   `Gesture` binds pointer input — `tap` and `doubletap` — to the same actions, minus `seekToPercent` and plus `toggleControls`. Bindings are scoped by `pointer` (`mouse` or `touch`) and `region` (`left`, `center`, `right`) — regions split the container’s width, not the rendered video’s — so double-tap-left rewinds while double-tap-right skips forward.
-*   `StatusAnnouncer` announces action results to screen readers, and the input indicator components render transient on-screen feedback (volume level, captions on/off) the way native players do. The prebuilt skins wire these up.
-
-The prebuilt skins bind the conventional set: Space and `k` toggle playback, `m` mutes, `f` fullscreens, `c` toggles captions, `i` toggles picture-in-picture, arrows seek and change volume, `j`/`l` seek in larger steps, `0`–`9` jump to a percentage, and `<`/`>` change speed.
-
-## Availability and constraints
-
-*   Hotkeys listen on the player container by default, so multiple players on a page don’t fight over keys. Pass `target="document"` on a hotkey to make it page-wide — appropriate only when one player owns the page.
-*   Typing is protected: while focus is in an editable field, single-key bindings are skipped automatically. Modifier combinations (for example `Ctrl+Shift+f`) still fire.
-*   Repeatable actions (seeking, volume) fire on held keys; toggle actions don’t repeat.
-*   Touch tap-to-toggle-controls and tap-to-pause are mutually exclusive per pointer type — the skins pause on mouse tap and toggle controls on touch tap, matching platform conventions.
-*   Gestures and the built-in touch handling coordinate through one recognizer; register gestures declaratively instead of adding raw pointer listeners next to them.
-
-## Common variations
-
-### Customize a shortcut
-
-Render your own `Hotkey` set instead of a skin’s: every binding is just an element, so add, remove, or re-key them freely.
-
-### Seek step size
-
-`seekStep` takes its step from `value` — match your content: 5 seconds for short clips, 15 or 30 for long-form.
-
-## Troubleshooting
-
-### Shortcuts don’t fire
-
-Focus is outside the player container. Click the player first, or move focus into it; hotkeys are player-scoped by design.
-
-### Double-tap seek also toggles pause
-
-Regions overlap: keep single-tap `togglePaused` on `center` only, and double-tap seek on `left` and `right`, as in the skin defaults.
-
-### No visual feedback on keyboard actions
-
-The input indicator components render that feedback; use a prebuilt skin or add `StatusAnnouncer` and the indicator components from the skin source to a custom UI.
-
-## Related components
-
-*   [Controls](../reference/controls.md)
-*   [Tooltip](../reference/tooltip.md)
-
-## Related API
-
-*   [Playback feature](../reference/feature-playback.md)
-*   [Volume feature](../reference/feature-volume.md)
-*   [Fullscreen feature](../reference/feature-fullscreen.md)
-
-## Related guides
-
-*   [Automatically show and hide controls](./show-and-hide-controls.md)
-*   [Accessibility](../concepts/accessibility.md)

package/docs/how-to/add-quality-selector.md

@@ -1,260 +0,0 @@
-# Add a quality selector
-
-Read available renditions, let the engine adapt automatically, and offer manual quality selection.
-
-Read the renditions a stream offers, let the streaming engine adapt quality automatically, and give users manual control when they want it.
-
-Quality selection applies to streaming sources. A progressive MP4 plays at one fixed quality and exposes no renditions; HLS and DASH streams offer several. See [Media sources](../concepts/media-sources.md).
-
-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
-
-This guide uses the hls.js media component, so install its adapter with the framework façade:
-
-bash
-
-```
-pnpm add @videojs/react @videojs/hlsjs-video
-```
-
-## Recommended approach
-
-Let automatic quality selection do its job by default, and offer a quality menu for users who want to pin a rendition. Render the menu only when quality selection is available.
-
-Quality
-
-App.tsx
-
-App.css
-
-```
-import { Container, createPlayer, Menu, QualityRadioGroup } from '@videojs/react';
-import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
-import { videoFeatures } from '@videojs/react/video';
-import type { ReactNode } from 'react';
-
-const { Player } = createPlayer({ features: videoFeatures });
-const src = 'https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4.m3u8';
-
-function QualityMenu(): ReactNode {
-  return (
-    <Menu.Root side="top" align="end">
-      <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
-        Quality
-      </Menu.Trigger>
-      <Menu.Popup className="menu">
-        <Menu.Content>
-          <QualityRadioGroup
-            className="menu-group"
-            renderItem={(props, item) => (
-              <Menu.RadioItem {...props} className="menu-item">
-                <span>
-                  {item.label}
-                  {item.tier ? <sup className="menu-tier">{item.tier}</sup> : null}
-                </span>
-                {item.badge ? <span className="menu-badge">{item.badge}</span> : null}
-                <Menu.ItemIndicator checked={item.checked} forceMount className="menu-indicator">
-                  ✓
-                </Menu.ItemIndicator>
-              </Menu.RadioItem>
-            )}
-          />
-        </Menu.Content>
-      </Menu.Popup>
-    </Menu.Root>
-  );
-}
-
-export default function BasicUsage() {
-  return (
-    <Player>
-      <Container className="media-container">
-        <HlsJsVideo src={src} autoPlay crossOrigin="anonymous" muted playsInline loop />
-        <div className="menu-bar">
-          <QualityMenu />
-        </div>
-      </Container>
-    </Player>
-  );
-}
-```
-```
-.media-container {
-  position: relative;
-}
-
-.media-container video {
-  width: 100%;
-}
-
-.menu-bar {
-  position: absolute;
-  right: 10px;
-  bottom: 10px;
-}
-
-.settings-trigger {
-  padding: 6px 16px;
-  color: black;
-  cursor: pointer;
-  background: rgba(255, 255, 255, 0.75);
-  border: 1px solid rgba(255, 255, 255, 0.35);
-  border-radius: 9999px;
-  backdrop-filter: blur(10px);
-}
-
-.menu {
-  --media-menu-side-offset: 8px;
-  box-sizing: border-box;
-  display: grid;
-  gap: 2px;
-  min-width: 180px;
-  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
-  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
-  padding: 6px;
-  margin: 0;
-  overflow: auto;
-  overscroll-behavior: none;
-  font-size: 14px;
-  color: white;
-  background: rgba(0, 0, 0, 0.88);
-  border: 0;
-  border-radius: 8px;
-  backdrop-filter: blur(10px);
-}
-
-.menu-group {
-  display: grid;
-  gap: 2px;
-}
-
-.menu-item {
-  display: flex;
-  gap: 8px;
-  align-items: center;
-  justify-content: space-between;
-  min-height: 32px;
-  padding: 0 10px;
-  font: inherit;
-  color: inherit;
-  cursor: pointer;
-  background: none;
-  border: 0;
-  border-radius: 6px;
-}
-
-.menu-item[data-highlighted] {
-  background: rgba(255, 255, 255, 0.16);
-}
-
-.menu-tier {
-  margin-left: 2px;
-  font-size: 10px;
-}
-
-.menu-badge {
-  margin-left: auto;
-  color: rgba(255, 255, 255, 0.72);
-}
-
-.menu-indicator {
-  opacity: 0;
-}
-
-[role="menuitemradio"][aria-checked="true"] .menu-indicator {
-  opacity: 1;
-}
-```
-
-## How it works
-
-The [quality feature](../reference/feature-quality.md) mirrors the media element’s video renditions into player state:
-
-*   `videoRenditionList` holds each rendition’s `id`, `width`, `height`, `bitrate`, `frameRate`, `codec`, and whether it’s `selected`.
-*   `activeVideoRendition` is the rendition currently playing. When the engine doesn’t report one directly, the player matches it from the video’s current dimensions.
-*   `selectVideoRendition(value)` pins one rendition; pass `'auto'` to return control to the engine’s adaptive selection.
-
-[`useQualityOptions`](../reference/use-quality-options.md) turns this state into ready-made menu options — labels like “1080p”, an “Auto” entry, and `availability` — as shown in the demo above.
-
-Selecting “Auto” keeps adaptive bitrate switching active: the engine picks the best rendition for current bandwidth and viewport. Pinning a rendition disables adaptation until the user selects “Auto” again.
-
-## Availability and constraints
-
-*   Quality availability is `'unavailable'` for media that doesn’t offer a choice — progressive files, streams before the manifest loads, and single-rendition streams. Render quality UI conditionally; the demo’s availability check does this.
-*   Renditions come from the streaming engine, so the list depends on what the manifest declares. A single-rendition stream offers no meaningful selection, so availability stays `'unavailable'`.
-*   Pinning a high rendition on a slow connection causes buffering: the engine can no longer step down. Keep “Auto” the default.
-*   Rendition lists change on source change; selection resets with them.
-
-## Common variations
-
-### Auto quality only
-
-If you don’t want to expose manual selection, do nothing: adaptive selection is on by default and needs no UI.
-
-### Cap or pin quality programmatically
-
-tsx
-
-```
-import { Container } from '@videojs/react';
-import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
-import { usePlayer, VideoPlayer } from '@videojs/react/video';
-
-function PinLowestRendition() {
-  const store = usePlayer();
-  const renditions = usePlayer((s) => s.videoRenditionList);
-
-  const lowest = [...renditions].sort((a, b) => (a.height ?? 0) - (b.height ?? 0))[0];
-
-  return (
-    <button type="button" onClick={() => lowest?.id && store.selectVideoRendition(lowest.id)}>
-      Data saver
-    </button>
-  );
-}
-
-export default function App() {
-  return (
-    <VideoPlayer>
-      <Container>
-        <HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" muted playsInline />
-        <PinLowestRendition />
-      </Container>
-    </VideoPlayer>
-  );
-}
-```
-
-## Troubleshooting
-
-### The quality menu doesn’t render
-
-Quality availability is `'unavailable'`. The source is progressive (no renditions), the manifest hasn’t loaded yet, or the media element doesn’t support renditions. Use a streaming media element such as the default [HlsVideo](../reference/hls-video.md) or [HlsJsVideo](../reference/hlsjs-video.md).
-
-### The menu doesn’t render for a single-rendition stream
-
-The manifest declares a single rendition, so quality availability stays `'unavailable'` — one entry offers no choice. Encode the stream as a multi-rendition ladder to give the engine and users something to choose between.
-
-### Playback buffers after selecting a quality
-
-The pinned rendition exceeds available bandwidth. Selecting “Auto” lets the engine step down again.
-
-## Related components
-
-*   [Quality radio group](../reference/quality-radio-group.md)
-*   [Menu](../reference/menu.md)
-
-## Related API
-
-*   [Quality feature](../reference/feature-quality.md)
-*   [useQualityOptions](../reference/use-quality-options.md)
-*   [HlsVideo](../reference/hls-video.md)
-*   [HlsJsVideo](../reference/hlsjs-video.md)
-*   [DashVideo](../reference/dash-video.md)
-
-## Related guides
-
-*   [Media sources](../concepts/media-sources.md)