npm - @videojs/react - Versions diffs - 10.0.0-rc.1 → 10.0.0-rc.3 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2773) hide show

package/docs/how-to/customize-skins.md DELETED Viewed

@@ -1,368 +0,0 @@
-# Customize skins
-Style a packaged Video.js skin or copy its source to change controls, layout, styles, and interactions
-Start with the path that matches the change you want:
-If you want to…
-Use this path
-Change colors, typography, sizing, or how the poster fills the player
-[Style a packaged skin](#style-a-packaged-skin). The skin stays in the Video.js package, and you set its supported CSS properties.
-Add, remove, rearrange, or deeply restyle controls; change layout or interactions
-[Eject and edit a skin](#eject-and-edit-a-skin). Ejecting copies the skin’s source files into your project so you can change them.
-## Style a packaged skin
-Use a packaged skin’s public settings to match it to your site without copying its source into your project.
-### Set the skin’s styles
-Packaged skins expose [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) for their supported visual changes. Set them on the skin or any element that contains it:
-tsx
-```
-<VideoSkin
-  style={
-    {
-      '--media-accent-color': '#f5c518',
-      '--media-border-radius': '1rem',
-    } as React.CSSProperties
-  }
->
-  <Video src="video.mp4" />
-</VideoSkin>
-```
-Property name
-What it changes
-Value
-Example
-`--media-accent-color`
-Slider fills, highlighted controls and menu items, and primary actions
-[`<color>`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)
-`#f5c518`
-`--media-accent-text-color`
-Text and icons shown on the accent color
-[`<color>`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)
-`black`
-`--media-border-color`
-The hairline around the player
-[`<color>`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value)
-`transparent`
-`--media-border-radius`
-The player corner radius
-A valid [border-radius value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/border-radius#values)
-`1rem`
-`--media-font-family`
-The player interface font stack
-A valid [font-family value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-family)
-`Roboto, sans-serif`
-`--media-object-fit`
-How the media and poster fill the player
-A valid [object-fit value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/object-fit)
-`cover`
-`--media-object-position`
-Where the media and poster sit when they do not fill the player
-A valid [object-position value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/object-position)
-`top`
-`--media-scale-unit`
-The base size for skin spacing, icons, and text
-[`<length>`](https://developer.mozilla.org/en-US/docs/Web/CSS/length)
-`1rem`
-If you omit `--media-accent-text-color`, the skins choose a contrasting text color from `--media-accent-color` using [`contrast-color()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/contrast-color). Set it only when you want a different result.
-The skins use [`Inter`](https://rsms.me/inter/) when your page loads it and fall back to the system UI font. Video.js does not load the webfont for you. Set `--media-font-family` to use another font.
-The media element and poster share `--media-object-fit` and `--media-object-position`, so a `cover` poster stays aligned with `cover` video. See [Add a poster and loading placeholder](./add-a-poster-and-loading-placeholder.md).
-### Set the color scheme
-The audio skins adapt their main palette for light and dark mode using [`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/light-dark). They read the inherited [`color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme), so set it on the player or an element that contains it:
-css
-```
-:root {
-  color-scheme: light dark;
-}
-```
-The video skins keep their dark controls in both color schemes. Only their hairline border follows the scheme, and `--media-border-color` replaces it.
-### Scale from the document font size
-The skins derive control spacing, icon sizes, and text from `--media-scale-unit`. It defaults to `16px`, so the player does not change with the document root font size or your app’s Tailwind spacing scale. Set it to `1rem` to make the interface scale from the document root font size:
-css
-```
-.player {
-  --media-scale-unit: 1rem;
-}
-```
-In fullscreen, the skins increase the unit up to 1.75 times on displays 1920 pixels and wider. This keeps controls legible from a distance.
-You can also add your own class names to the skins.
-### Know where packaged styling stops
-The properties above are the public styling settings for packaged skins. Do not depend on the elements, class names, or other custom properties inside a packaged skin. They may change between releases.
-Packaged video skins also let you replace the poster through the `renderPoster` prop.
-See [Poster](../reference/poster.md).
-Packaged skins do not provide settings for adding, removing, or rearranging controls, or for replacing built-in feedback and interactions. To make those changes, [eject the closest skin](#eject-and-edit-a-skin) and edit its source.
-## Eject and edit a skin
-If a packaged skin is close to the interface you want, eject it and edit the copy in your project. Ejecting turns the skin’s controls, layout, styles, and interactions into app code that you own.
-Video.js publishes the skin source in a catalog of installable files. The [`shadcn` CLI](https://ui.shadcn.com/docs/cli) is the command-line tool that copies those files into your project, whether you use React or HTML.
-Note
-Commit your work before installing or updating source. You can then review every file the CLI adds or replaces.
-### Set up the `shadcn` CLI
-If your project does not have a `components.json` configuration file, create one:
-npm
-pnpm
-yarn
-bun
-```
-npx shadcn@latest init
-```
-```
-pnpm dlx shadcn@latest init
-```
-```
-yarn dlx shadcn@latest init
-```
-```
-bunx --bun shadcn@latest init
-```
-### Choose how the skin is styled
-Each React skin is available with Tailwind CSS 4 classes or with a plain stylesheet, labeled Vanilla CSS. Choose the form your project uses. Skin names stay the same.
-StylingTailwind CSS
-### Connect the CLI to Video.js
-Run this command once. It saves `@videojs` as a short prefix in `components.json`, so later commands can use names such as `@videojs/video`:
-npm
-pnpm
-yarn
-bun
-```
-npx shadcn@latest registry add @videojs=https://shadcn.videojs.org/r/react/{name}.json
-```
-```
-pnpm dlx shadcn@latest registry add @videojs=https://shadcn.videojs.org/r/react/{name}.json
-```
-```
-yarn dlx shadcn@latest registry add @videojs=https://shadcn.videojs.org/r/react/{name}.json
-```
-```
-bunx --bun shadcn@latest registry add @videojs=https://shadcn.videojs.org/r/react/{name}.json
-```
-### Install a skin
-Install the skin closest to the interface you want. Default skins use the preset name, and Minimal skins add `-minimal`:
-npm
-pnpm
-yarn
-bun
-```
-npx shadcn@latest add @videojs/video
-```
-```
-pnpm dlx shadcn@latest add @videojs/video
-```
-```
-yarn dlx shadcn@latest add @videojs/video
-```
-```
-bunx --bun shadcn@latest add @videojs/video
-```
-Skin
-Install name
-Installs to
-Default Video
-`@videojs/video`
-`components/videojs/skins/video`
-Minimal Video
-`@videojs/video-minimal`
-`components/videojs/skins/video/minimal`
-Default Audio
-`@videojs/audio`
-`components/videojs/skins/audio`
-Minimal Audio
-`@videojs/audio-minimal`
-`components/videojs/skins/audio/minimal`
-Default Live Video
-`@videojs/live-video`
-`components/videojs/skins/live-video`
-Minimal Live Video
-`@videojs/live-video-minimal`
-`components/videojs/skins/live-video/minimal`
-Default Live Audio
-`@videojs/live-audio`
-`components/videojs/skins/live-audio`
-Minimal Live Audio
-`@videojs/live-audio-minimal`
-`components/videojs/skins/live-audio/minimal`
-The paths in the table start from the component location configured in `components.json`. The background video skin cannot be ejected.
-### Use the installed skin
-The skin’s files are under `components/videojs/skins/<preset>`. Keep importing the player and media from `@videojs/react`. Import the installed skin component from `skin.tsx`, then render it around your media where you previously rendered the packaged skin.
-### Edit the installed files
-Start with the file that owns the change you want:
-Goal
-Where to start
-Add, remove, or rearrange controls
-`skin.tsx` in React or `skin.html` in HTML
-Change colors, surfaces, shadows, sizes, or motion across the skin
-`components/videojs/styles/theme.css`
-Change one control’s appearance
-That control’s classes or stylesheet
-Change one control’s interaction
-That control’s module
-The files for the control bar, gestures, keyboard shortcuts, settings menu, and status indicators are composed from `skin.tsx`. The UI components they use are installed as source too, so you can open and change each button or slider.
-*   **Tailwind CSS.** Components use utility classes. The install adds the theme keys, utilities, and variants to your main CSS file. The skins require Tailwind CSS 4.3 or later and its default configuration. If your project prefixes Tailwind classes, update the installed components.
-*   **Vanilla CSS.** Components use class names that start with `media-`, and the skin’s `skin.css` stylesheet styles them.
-### Inspect or update an ejected skin
-Use the CLI’s `search` command to find source and `view` to inspect it before installation:
-bash
-```
-npx shadcn@latest search @videojs --query volume
-npx shadcn@latest view @videojs/video
-```
-Installed files belong to your project, so an update replaces your local copy. Commit your changes, reinstall with `--overwrite`, and review the resulting version-control diff before keeping it:
-bash
-```
-npx shadcn@latest add @videojs/video --overwrite
-```
-To understand how skins fit into Video.js, read [Skins](../concepts/skins.md). To create a control instead of editing one, follow [Build your own component](./build-your-own-component.md).

package/docs/how-to/go-fullscreen-and-lock-orientation.md DELETED Viewed

@@ -1,153 +0,0 @@
-# Go fullscreen and lock orientation
-Present the player fullscreen with custom controls intact, and lock screen orientation on mobile.
-Present the player fullscreen, with your custom controls intact, and optionally lock screen orientation while fullscreen on mobile.
-Note
-Using a pre-built [skin](../concepts/skins.md)? It already includes the controls shown here. You may still need the media or player setup in this guide. The component examples are for building your own player UI from individual [components](../concepts/ui-components.md).
-## Recommended approach
-Add a [FullscreenButton](../reference/fullscreen-button.md) inside the player container. It requests fullscreen on the container, so everything inside it — controls, captions, overlays — stays visible in the fullscreen presentation.
-App.tsx
-App.css
-```
-import { Container, createPlayer, FullscreenButton } 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 />
-        <FullscreenButton
-          className="media-fullscreen-button"
-          render={(props, state) => <button {...props}>{state.fullscreen ? 'Exit Fullscreen' : 'Fullscreen'}</button>}
-        />
-      </Container>
-    </Player>
-  );
-}
-```
-```
-.media-container {
-  position: relative;
-}
-.media-container video {
-  width: 100%;
-}
-.media-fullscreen-button {
-  position: absolute;
-  right: 10px;
-  bottom: 10px;
-  padding-block: 8px;
-  padding-inline: 20px;
-  color: black;
-  cursor: pointer;
-  background: rgba(255, 255, 255, 0.7);
-  border: 1px solid rgba(255, 255, 255, 0.3);
-  border-radius: 9999px;
-  backdrop-filter: blur(10px);
-}
-```
-## How it works
-The [fullscreen feature](../reference/feature-fullscreen.md) tracks fullscreen state and provides the actions:
-*   `fullscreen` is `true` while the player is fullscreen, from any path — your button, native controls, or the platform presentation.
-*   `fullscreenAvailability` is `'available'`, `'unavailable'`, or `'unsupported'`. It starts as `'unavailable'`, then settles to `'available'` or `'unsupported'` when the feature attaches to a media element.
-*   `requestFullscreen()`, `exitFullscreen()`, and `toggleFullscreen()` change the presentation. Requests target the player container when the Fullscreen API is available, falling back to the media element’s native presentation otherwise.
-Fullscreen and picture-in-picture are exclusive: requesting fullscreen exits an active picture-in-picture presentation first.
-Style fullscreen state through the container’s `:fullscreen` pseudo-class, or through the `fullscreen` state in components.
-## Availability and constraints
-*   Fullscreen requests must come from a user gesture; browsers reject requests outside one.
-*   iPhone Safari has no element Fullscreen API. The player falls back to the video’s native fullscreen presentation, which shows the system player UI instead of your custom controls. iPads support element fullscreen.
-*   Orientation locking requires the Screen Orientation API with lock support — in practice, Android browsers in fullscreen. iOS doesn’t support programmatic orientation lock.
-*   Inside iframes, fullscreen needs `allow="fullscreen"` on the embedding iframe.
-## Common variations
-### Lock orientation while fullscreen
-Add `orientationLockFeature` to lock screen orientation while the player is fullscreen. It isn’t part of `videoFeatures`, so the preset `VideoPlayer` doesn’t include it. It locks to `landscape` by default and unlocks on exit.
-Because the feature list changes, build the player yourself with [`createPlayer`](../reference/create-player.md) — the escape hatch for custom feature sets:
-tsx
-```
-import { Container, createPlayer, orientationLockFeature } from '@videojs/react';
-import { Video, videoFeatures } from '@videojs/react/video';
-const { Player } = createPlayer({
-  features: [...videoFeatures, orientationLockFeature],
-});
-export default function App() {
-  return (
-    <Player>
-      <Container>
-        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
-      </Container>
-    </Player>
-  );
-}
-```
-To lock to something other than `landscape`, set `orientationLockType` on the player (the `orientation-lock-type` attribute in HTML). See the [orientation lock feature](../reference/feature-orientation-lock.md) reference for details.
-### Double-click to toggle
-Use the `Gesture` component — the default skins ship this exact binding. Keep the button as the accessible path; gestures are a pointer-only shortcut.
-tsx
-```
-import { Gesture } from '@videojs/react';
-<Gesture type="doubletap" action="toggleFullscreen" region="center" />
-```
-`region="center"` keeps the gesture off the left and right thirds, which the default skins reserve for double-tap seeking. See [Add keyboard shortcuts and gestures](./add-keyboard-shortcuts-and-gestures.md) for the full gesture surface.
-## Troubleshooting
-### The fullscreen request is rejected
-The request didn’t come from a user gesture, fullscreen is unsupported, or an embedding iframe lacks `allow="fullscreen"`.
-### Custom controls disappear in fullscreen on iPhone
-Expected: iPhone Safari uses the native video presentation, which replaces custom UI with system controls. Design mobile controls assuming this fallback.
-### Orientation doesn’t lock
-Orientation lock works in fullscreen on Android browsers; iOS doesn’t support it. Confirm `orientationLockFeature` is in your feature list.
-## Related components
-*   [Fullscreen button](../reference/fullscreen-button.md)
-*   [Player container](../reference/player-container.md)
-## Related API
-*   [Fullscreen feature](../reference/feature-fullscreen.md)
-*   [Orientation lock feature](../reference/feature-orientation-lock.md)
-## Related guides
-*   [Use picture-in-picture](./use-picture-in-picture.md)

package/docs/how-to/handle-playback-errors.md DELETED Viewed

@@ -1,92 +0,0 @@
-# Handle playback errors
-Surface terminal playback errors and give users a useful next step.
-Surface terminal playback errors instead of leaving a dead player, and give users a useful next step.
-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
-Render an [ErrorDialog](../reference/error-dialog.md) inside the player container. It reads error state, presents the failure, and dismisses cleanly. The prebuilt skins include one.
-tsx
-```
-import { Container, ErrorDialog } 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 />
-        <ErrorDialog.Root>
-          <ErrorDialog.Popup className="media-error">
-            <ErrorDialog.Title />
-            <ErrorDialog.Description />
-            <ErrorDialog.Close>Dismiss</ErrorDialog.Close>
-          </ErrorDialog.Popup>
-        </ErrorDialog.Root>
-      </Container>
-    </VideoPlayer>
-  );
-}
-```
-## How it works
-The [error feature](../reference/feature-error.md) mirrors the media element’s error into player state:
-*   `error` holds the media’s `MediaError` — `code`, `message` — or `null` when there is none.
-*   `dismissError()` clears the error from player state (the media element keeps its own error until a new load).
-*   Loading a new source resets `error` to `null` automatically.
-The dialog owns presentation, not recovery. Decide the next step in your application: let the user dismiss the message, choose another item, refresh an expired URL, or contact support.
-## Availability and constraints
-*   A media error is terminal for the current load: playback won’t resume without loading a source again.
-*   `MediaError.code` distinguishes broad classes — aborted, network, decode, and source-not-supported — not root causes. Check the network panel for the real story (404, CORS, codec).
-*   Streaming engines handle recoverable segment and network failures before surfacing a terminal error. Do not layer a generic same-source retry loop on top of the engine.
-*   Once the player attaches to the media element, errors land in state even before any UI renders (bad URL at mount); make sure your error surface renders regardless of playback state.
-## Common variations
-### Offer an application-specific next step
-Use the error code and your product context to choose the action. A live event can link to its status page, an authenticated app can refresh an expired playback URL, and a playlist can offer the next item. Keep that action outside `ErrorDialog`; the dialog can close after your application has handled it.
-### Report errors to monitoring
-Subscribe to error state and forward it to your error tracker with the source URL and `error.code`; media errors are invisible in JavaScript error monitoring unless you send them.
-## Troubleshooting
-### The player is black and silent with no error
-Not every dead player is a media error — autoplay blocking and an unset source produce no error. Check `error`, `source`, and `paused` in player state to tell them apart.
-### Error code says the source isn’t supported
-The browser can’t play the format through this media element. HLS in a plain video element outside Safari is the classic case; use the matching streaming media element. See [Media sources](../concepts/media-sources.md).
-### Reopening the source produces the same error
-The failure is probably permanent for that source, such as a 404, revoked token, unsupported codec, or CORS response. Fix or replace the source instead of repeatedly loading the same URL.
-## Related components
-*   [Buffering indicator](../reference/buffering-indicator.md)
-## Related API
-*   [Error feature](../reference/feature-error.md)
-## Related guides
-*   [Media sources](../concepts/media-sources.md)
-*   [Autoplay](./autoplay.md)