# Video.js v10 — React Guides (complete)
> Every React guides page in one file (about 95k tokens). Index with descriptions: https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/llms.txt
---
# React Installation Guide
Install Video.js in React and build an accessible, customizable video player with composable controls
Video.js is a **React video player component library**: composable primitives, hooks, and TypeScript types for building accessible, customizable players with minimal bundle sizes, advanced features, and consistency across browsers.
> **Note: Release Candidate**
>
> Video.js v10 is a *release candidate*. We feel the API is stable and ready to build with. With your [feedback](https://github.com/videojs/v10/issues), a few documentation updates, and any final fixes, we look forward to shipping 10.0.0 soon. [Read the Release Candidate blog post](https://deploy-preview-2971--vjs10-site.netlify.app/blog/videojs-v10-release-candidate).
> **Tip: Coming from another player?**
>
> Follow the migration guide for [Video.js 8](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-video-js-8), [Mux Player](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-mux-player), [Plyr](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr), or [Media Chrome](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-media-chrome). Each maps your existing setup onto Video.js v10 instead of starting from scratch.
## AI Quickstart
Paste this prompt into your coding agent:
```
Install the Video.js skill using one method. In Codex, run `codex plugin marketplace add videojs/skills`, then `codex plugin add videojs@videojs`, and start a new session. In Claude Code, run `claude plugin marketplace add videojs/skills`, then `claude plugin install videojs@videojs`, and start a new session or run `/reload-plugins`. In VS Code or Cursor, install `https://github.com/videojs/skills` as a plugin from source. For another agent, run `npx skills add https://github.com/videojs/skills --skill videojs` and select the agent. Then use the Video.js skill when working on this project.
```
## Choose your JS framework
Your framework determines which installation methods are available below.
- [React](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/react): Components and hooks for React 19. Available methods: Packaged, Shadcn.
- [HTML](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/html): Custom elements for any stack. Available methods: Packaged, Shadcn, CDN.
- [Vue](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/vue): Vue 3 and Nuxt using the HTML custom elements. Available methods: Packaged, Shadcn.
- [Svelte](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/svelte): Svelte 5 and SvelteKit using the HTML custom elements. Available methods: Packaged, Shadcn.
## Choose your use case
- [Video](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets#preset-video) (`video`): On-demand video with full controls.
- [Audio](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets#preset-audio) (`audio`): Podcasts, music, and audio-only playback.
- [Live Video](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets#preset-live-video) (`live-video`): Streams with a Live button, no duration.
- [Live Audio](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets#preset-live-audio) (`live-audio`): Live radio and audio streams.
- [Background Video](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets#preset-background) (`background-video`): Muted, looping video behind your content.
The live presets suit streams: they drop the duration and current-time displays that on-demand playback relies on, and they offer only media that exposes live-edge state.
## Choose your skin
- **Default** (`default`): the complete control set with a modern, frosted look. Reference pages: [`VideoSkin`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/video-skin), [`AudioSkin`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/audio-skin), [`LiveVideoSkin`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/live-video-skin), and [`LiveAudioSkin`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/live-audio-skin).
- **Minimal** (`minimal`): the same control set with clean, solid surfaces. Reference pages: [`MinimalVideoSkin`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/video-minimal-skin), [`MinimalAudioSkin`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/audio-minimal-skin), [`MinimalLiveVideoSkin`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/live-video-minimal-skin), and [`MinimalLiveAudioSkin`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/live-audio-minimal-skin).
- **No skin** (`none`): player and media behavior without a packaged UI.
Background Video always uses [`BackgroundVideoSkin`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/background-video-skin), whatever skin you choose.
## Choose your media source
Available media sources depend on the use case:
| Media source | Use cases | React component | Adapter package |
| --- | --- | --- | --- |
| HTML5 Video (`html5-video`) | Video | [`Video`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/video) | None |
| HLS (`hls`) | Video, Live Video | [`HlsJsVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hlsjs-video) | `@videojs/hlsjs-video` |
| DASH (`dash`) | Video | [`DashVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/dash-video) | `@videojs/dash-video` |
| Mux (`mux-video`) | Video, Live Video | [`MuxVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-video) | `@videojs/mux-video` |
| Vimeo (`vimeo`) | Video | [`VimeoVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/vimeo-video) | `@videojs/vimeo-video` |
| YouTube (`youtube`) | Video | [`YouTubeVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/youtube-video) | `@videojs/youtube-video` |
| Cloudflare Stream (`cloudflare`) | Video | [`CloudflareVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/cloudflare-video) | `@videojs/cloudflare-video` |
| TikTok (`tiktok`) | Video | [`TikTokVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/tiktok-video) | `@videojs/tiktok-video` |
| Twitch (`twitch`) | Video | [`TwitchVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/twitch-video) | `@videojs/twitch-video` |
| HTML5 Audio (`html5-audio`) | Audio | [`Audio`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/audio) | None |
| Mux (`mux-audio`) | Audio, Live Audio | [`MuxAudio`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-audio) | `@videojs/mux-audio` |
| Spotify (`spotify`) | Audio | [`SpotifyAudio`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/spotify-audio) | `@videojs/spotify-audio` |
| Background Video (`background-video`) | Background Video | [`BackgroundVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/background-video) | None |
HLS uses `HlsJsVideo` for broad compatibility. To reduce your bundle size, try our lightweight HLS engine, [`HlsVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hls-video).
The keys in parentheses are the values the docs CLI (`npx @videojs/cli docs guides/installation/react`) accepts for its `--preset`, `--skin`, and `--media` flags. Run noninteractively, it also needs `--source-url` (pass `''` for demo media) and `--package-manager` (`npm`, `pnpm`, `yarn`, or `bun`).
## Choose how to install
Pick one starting path. These are alternatives, not steps to run in sequence. Shadcn does not provide source for background video or a no-skin player. CDN availability also depends on the selected media source.
- [Packaged](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/react): Install packages and use a ready-made skin.
- [Shadcn](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/shadcn): Add editable React or HTML skin source to your project.
The code below is a complete example for the default Video, Default skin, and HTML5 Video choices with demo media. For another combination, swap in the imports and markup from the preset, skin, and media reference pages linked above, and replace the demo URL with your own.
If a preset and skin do not meet your user’s requirements, follow [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source) to add the files for the closest skin to the project. As you develop with Video.js, rely heavily on [llms.txt](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/llms.txt) to make sure you always have the latest information.
## Install the packages
**npm**
```bash
npm install @videojs/react
```
**pnpm**
```bash
pnpm add @videojs/react
```
**yarn**
```bash
yarn add @videojs/react
```
**bun**
```bash
bun add @videojs/react
```
## Add your player
Add the player directly to `app/page.tsx`. It imports the selected player, skin, media, and extensions from the packages you installed.
**app/page.tsx**
```tsx
import '@videojs/react/video/skin.css';
import { VideoPlayer, VideoSkin, Video } from '@videojs/react/video';
export default function Page() {
return (
);
}
```
That’s it! You now have a working Video.js player.
## Own the UI
Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.
- [Install Video.js with Shadcn](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/shadcn?framework=react): Add editable skin source and build a working React or HTML player
## Choose what to do next
### Customize
- [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-a-packaged-skin): Change colors, typography, sizing, and poster presentation
- [UI components](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/architecture#ui-components): Explore the building blocks used by skins and custom controls
- [Build your own component](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/build-your-own-component): Connect custom UI to player state and actions
### Deploy
- [Browser support](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/browser-support): Check supported browsers and rendering environments
- [TypeScript](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/typescript): Configure TypeScript for Video.js packages
- [Bundlers](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/bundlers): Check bundler compatibility
- [Content Security Policy](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/content-security-policy): Configure Content Security Policy for your player
Something not quite right? You can [submit an issue](https://github.com/videojs/v10/issues) and ask for help, or explore [other support options](https://deploy-preview-2971--vjs10-site.netlify.app/html5-video-support).
---
# Shadcn Installation Guide
Use the Video.js Shadcn registry to add editable React or HTML custom-element skin source to your project
Use Shadcn to add a Video.js skin's components, layout, styles, and interactions as React or HTML custom-element source. The CLI copies the files into your app so you can review and change them like any other source code.
> **Note: Release Candidate**
>
> Video.js v10 is a *release candidate*. We feel the API is stable and ready to build with. With your [feedback](https://github.com/videojs/v10/issues), a few documentation updates, and any final fixes, we look forward to shipping 10.0.0 soon. [Read the Release Candidate blog post](https://deploy-preview-2971--vjs10-site.netlify.app/blog/videojs-v10-release-candidate).
> **Tip: Coming from another player?**
>
> Follow the React migration guide for [Video.js 8](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-video-js-8), [Mux Player](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-mux-player), [Plyr](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr), or [Media Chrome](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-media-chrome). Each maps your existing setup onto Video.js v10 instead of starting from scratch.
## AI Quickstart
Paste this prompt into your coding agent:
```
Install the Video.js skill using one method. In Codex, run `codex plugin marketplace add videojs/skills`, then `codex plugin add videojs@videojs`, and start a new session. In Claude Code, run `claude plugin marketplace add videojs/skills`, then `claude plugin install videojs@videojs`, and start a new session or run `/reload-plugins`. In VS Code or Cursor, install `https://github.com/videojs/skills` as a plugin from source. For another agent, run `npx skills add https://github.com/videojs/skills --skill videojs` and select the agent. Then use the Video.js skill when working on this project.
```
## Choose your JS framework
Your framework determines which installation methods are available below.
- [React](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/react): Components and hooks for React 19. Available methods: Packaged, Shadcn.
- [HTML](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/html): Custom elements for any stack. Available methods: Packaged, Shadcn, CDN.
- [Vue](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/vue): Vue 3 and Nuxt using the HTML custom elements. Available methods: Packaged, Shadcn.
- [Svelte](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/svelte): Svelte 5 and SvelteKit using the HTML custom elements. Available methods: Packaged, Shadcn.
The Shadcn registry generates React or HTML source. Vue and Svelte can use the HTML custom-element source.
- **React** (`react`)
- Project templates: Next.js (`next`), Vite (`vite`), TanStack Start (`start`), Laravel (`laravel`), React Router (`react-router`), Astro (`astro`)
- Styling: Tailwind CSS (`tailwind`), Vanilla CSS (`css`)
- **HTML** (`html`)
- Project templates: Vite (`vite`), Astro (`astro`), Laravel (`laravel`)
- Styling: Vanilla CSS (`css`)
## Choose your use case
- **Video** (`video`): On-demand video with full controls.
- **Audio** (`audio`): Podcasts, music, and audio-only playback.
- **Live Video** (`live-video`): Streams with a Live button, no duration.
- **Live Audio** (`live-audio`): Live radio and audio streams.
The live presets suit streams: they drop the duration and current-time displays that on-demand playback relies on, and they offer only media that exposes live-edge state.
## Choose your skin
- **Default** (`default`): the complete control set with a modern, frosted look.
- **Minimal** (`minimal`): the same control set with clean, solid surfaces.
Shadcn copies either the Default or Minimal skin source into the project. It does not currently provide the background video skin or a no-skin option.
## Choose your media source
Available media sources depend on the use case:
| Media source | Use cases | React component | HTML element | Adapter package |
| --- | --- | --- | --- | --- |
| HTML5 Video (`html5-video`) | Video | [`Video`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/video) | [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/components/video) | None |
| HLS (`hls`) | Video, Live Video | [`HlsJsVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hlsjs-video) | [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/components/hlsjs-video) | `@videojs/hlsjs-video` |
| DASH (`dash`) | Video | [`DashVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/dash-video) | [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/components/dash-video) | `@videojs/dash-video` |
| Mux (`mux-video`) | Video, Live Video | [`MuxVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-video) | [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/components/mux-video) | `@videojs/mux-video` |
| Vimeo (`vimeo`) | Video | [`VimeoVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/vimeo-video) | [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/components/vimeo-video) | `@videojs/vimeo-video` |
| YouTube (`youtube`) | Video | [`YouTubeVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/youtube-video) | [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/components/youtube-video) | `@videojs/youtube-video` |
| Cloudflare Stream (`cloudflare`) | Video | [`CloudflareVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/cloudflare-video) | [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/components/cloudflare-video) | `@videojs/cloudflare-video` |
| TikTok (`tiktok`) | Video | [`TikTokVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/tiktok-video) | [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/components/tiktok-video) | `@videojs/tiktok-video` |
| Twitch (`twitch`) | Video | [`TwitchVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/twitch-video) | [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/components/twitch-video) | `@videojs/twitch-video` |
| HTML5 Audio (`html5-audio`) | Audio | [`Audio`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/audio) | [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/components/audio) | None |
| Mux (`mux-audio`) | Audio, Live Audio | [`MuxAudio`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-audio) | [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/components/mux-audio) | `@videojs/mux-audio` |
| Spotify (`spotify`) | Audio | [`SpotifyAudio`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/spotify-audio) | [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/components/spotify-audio) | `@videojs/spotify-audio` |
HLS uses `HlsJsVideo` or `` for broad compatibility. To reduce your bundle size, try our lightweight HLS engine, [`HlsVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hls-video) or [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/components/hls-video).
The keys in parentheses are the values the docs CLI (`npx @videojs/cli docs guides/installation/shadcn`) accepts for its `--framework`, `--template`, `--styling`, `--preset`, `--theme`, and `--media` flags. Run noninteractively, it also needs `--source-url` (pass `''` for demo media) and `--package-manager` (`npm`, `pnpm`, `yarn`, or `bun`).
## Choose how to install
Pick one starting path. These are alternatives, not steps to run in sequence. Shadcn does not provide source for background video or a no-skin player. CDN availability also depends on the selected media source.
- Packaged ([React](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/react) or [HTML](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/html)): Install packages and use a ready-made skin.
- [Shadcn](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/shadcn): Add editable React or HTML skin source to your project.
- [CDN](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/cdn): Load the HTML player from jsDelivr without a package manager or build step.
The steps below use the default Video, Default skin, and HTML5 Video choices with demo media. Each step notes what changes for other choices. Swap in the media component from its reference page linked above, and replace the demo URL with your own.
## Initialize Shadcn
Run the commands from the app directory that contains `components.json`, or where you want the CLI to create it. In a monorepo, run them from the app workspace or pass `--cwd `.
> **Note**
>
> Commit your work before installing or updating source so you can review every file the CLI adds or replaces.
### React
**npm**
```bash
npx shadcn@latest init --template next
```
**pnpm**
```bash
pnpm dlx shadcn@latest init --template next
```
**yarn**
```bash
yarn dlx shadcn@latest init --template next
```
**bun**
```bash
bunx --bun shadcn@latest init --template next
```
These commands initialize Shadcn with the Next.js template. For another project template, replace `next` with `vite` (Vite), `start` (TanStack Start), `laravel` (Laravel), `react-router` (React Router), or `astro` (Astro).
If the app already has `components.json`, skip this section.
## Add the skin source
React skins can use Tailwind CSS 4 or Vanilla CSS. HTML skins use Vanilla CSS. Choose the styling that matches your app, then connect the Video.js registry and add the skin selected above.
### React
**npm**
```bash
npx shadcn@latest registry add @videojs=https://shadcn.videojs.org/r/react/{name}.json
npx shadcn@latest add @videojs/video
```
**pnpm**
```bash
pnpm dlx shadcn@latest registry add @videojs=https://shadcn.videojs.org/r/react/{name}.json
pnpm dlx shadcn@latest add @videojs/video
```
**yarn**
```bash
yarn dlx shadcn@latest registry add @videojs=https://shadcn.videojs.org/r/react/{name}.json
yarn dlx shadcn@latest add @videojs/video
```
**bun**
```bash
bunx --bun shadcn@latest registry add @videojs=https://shadcn.videojs.org/r/react/{name}.json
bunx --bun shadcn@latest add @videojs/video
```
These commands add the Default Video skin with Tailwind CSS. For another skin or styling, pass the matching catalog URL to `registry add`:
| Styling | Default skin (`default`) | Minimal skin (`minimal`) |
| --- | --- | --- |
| Tailwind CSS (`tailwind`) | `https://shadcn.videojs.org/r/react/{name}.json` | `https://shadcn.videojs.org/r/react/minimal/{name}.json` |
| Vanilla CSS (`css`) | `https://shadcn.videojs.org/r/react/css/{name}.json` | `https://shadcn.videojs.org/r/react/css/minimal/{name}.json` |
Then add the item for your use case: `@videojs/video`, `@videojs/audio`, `@videojs/live-video`, or `@videojs/live-audio`.
The files are added under `components/videojs/`. The registry item also installs `@videojs/react`.
## Add your player
### React
Add the player directly to `app/page.tsx`. It imports the player and media from the package, then imports the selected skin from your project.
**app/page.tsx**
```tsx
import { VideoPlayer, Video } from '@videojs/react/video';
import { VideoSkin } from '@/components/videojs/video/skin';
export default function Page() {
return (
);
}
```
That’s it! You now have a working Video.js player whose skin source lives in your project.
## Change the skin source
### React
Start in `components/videojs//skin.tsx`. Follow the [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source) guide for the files that control layout, colors, controls, and interactions.
## Choose what to do next
### React
#### Customize
- [Customize skin source](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source): Change the installed layout, controls, styles, and interactions
- [UI components](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/architecture#ui-components): Explore the building blocks used by skins and custom controls
- [Build your own component](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/build-your-own-component): Connect custom UI to player state and actions
#### Deploy
- [Browser support](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/browser-support): Check supported browsers and rendering environments
- [TypeScript](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/typescript): Configure TypeScript for Video.js packages
- [Bundlers](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/bundlers): Check bundler compatibility
- [Content Security Policy](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/content-security-policy): Configure Content Security Policy for your player
---
# Build your own UI component
Create custom player controls that read state, dispatch actions, and stay accessible.
Custom components subscribe to player state and dispatch actions, like built-in controls.
## You might not need a custom component
Before building from scratch, check if an existing approach covers your use case:
- **Change what a control renders**: use the `render` prop on any built-in component. See [UI components](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components).
- **Restyle a control**: use CSS custom properties and data attributes. See [UI components](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components).
- **Rearrange or remove controls**: add the skin source to your project, then modify it. See [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source).
Build a custom component when you need new behavior, a new state display, or integration with an external system.
## Place your component in the player
Your component needs to be inside [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/player) to access state. Place it inside [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/player-container) if it should also participate in fullscreen and respond to user activity:
```tsx
import { Container } from '@videojs/react';
```
## Full example
A “skip intro” button that appears during the first 30 seconds of playback and seeks past the intro when clicked.
**SkipIntroButton.tsx**
```tsx
// The preset's usePlayer is typed for its feature bundle
import { usePlayer } from '@videojs/react/video';
export function SkipIntroButton() {
const store = usePlayer();
const currentTime = usePlayer((s) => s.currentTime);
const paused = usePlayer((s) => s.paused);
const visible = currentTime < 30 && !paused;
return (
store.seek(30)}
aria-label="Skip intro"
// `undefined` removes the attribute; `false` would render data-visible="false"
data-visible={visible || undefined}
tabIndex={visible ? 0 : -1}
>
Skip intro
);
}
```
**SkipIntroButton.css**
```css
.skip-intro-button {
position: absolute;
bottom: 5rem;
right: 1rem;
opacity: 0;
pointer-events: none;
transition: opacity 200ms;
}
.skip-intro-button[data-visible] {
opacity: 1;
pointer-events: auto;
}
```
Your component needs to be inside a player, such as [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/player), to access state. Place it inside [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/player-container) if it should also participate in fullscreen and respond to user activity:
```tsx
import { Container } from '@videojs/react';
import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
import '@videojs/react/video/skin.css';
import { SkipIntroButton } from './SkipIntroButton';
export default function App() {
return (
);
}
```
## How it works
Custom components read player state and dispatch actions through [features](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features). Each feature exposes a set. Here are some features you might reach for first:
| State | Actions | Feature |
| --- | --- | --- |
| `paused`, `ended` | `play()`, `pause()` | [Playback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback) |
| `currentTime`, `duration` | `seek()` | [Time](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-time) |
| `volume`, `muted` | `setVolume()`, `toggleMuted()` | [Volume](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-volume) |
| `fullscreen` | `requestFullscreen()`, `exitFullscreen()` | [Fullscreen](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-fullscreen) |
The API reference lists every feature with the state and actions it adds.
Access state and actions with the [`usePlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-player) hook from your player’s preset. It knows which features that preset has, so state and actions are typed. (The standalone `usePlayer` export from `@videojs/react` returns an untyped store, so its values are `unknown` in TypeScript.) If you built the player with a custom feature set through [`createPlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/create-player) — the escape hatch for custom feature sets — use the `usePlayer` it returns instead.
```tsx
import { usePlayer } from '@videojs/react/video';
// Subscribe to state — re-renders only when selected values change
const paused = usePlayer((s) => s.paused);
const currentTime = usePlayer((s) => s.currentTime);
// Get the store for dispatching actions (does not subscribe)
const store = usePlayer();
await store.play();
store.setVolume(0.5);
store.seek(30);
```
Custom controls also need real button semantics — the examples above set the accessible name and keyboard focus by hand.
- [Learn more about accessibility in video players](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/accessibility)
## Availability and constraints
- Features are configured per player, so a feature your component asks for may not be present. Selectors return `undefined` for a missing feature; guard the value before using it, as the example does.
- Volume, fullscreen, picture-in-picture, and remote playback also expose an `*Availability` property (`'available'`, `'unavailable'`, or `'unsupported'`) for hiding controls the platform does not support. See [Features](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features) for details.
## Common variations
Before building from scratch, check if an existing approach covers your use case. Build a custom component when you need new behavior, a new state display, or integration with an external system.
### Change what a built-in control renders
Use the `render` prop on any built-in component. See [UI components](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components).
### Restyle a control
Use CSS custom properties and data attributes. See [UI components](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components).
### Rearrange or remove controls
Add the skin source to your project and modify it. See [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source).
## Troubleshooting
### State and actions are typed as `unknown`
You’re using the standalone `usePlayer` export, which doesn’t know which features your player has. Import `usePlayer` from your player’s preset (for example `@videojs/react/video`), or use the hook returned by `createPlayer` if you built the player with a custom feature set.
### The component renders but never updates
The component sits outside the player (such as ``), so `usePlayer` has no store to subscribe to.
## Related pages
### API
- [usePlayer](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-player): Hook to access the player store from within a Player
- [createPlayer](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/create-player): Factory function that creates a typed Player component and hooks
- [Container](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/player-container): The player's visual and interaction surface for layout, fullscreen, focus, and user activity.
### Guides
- [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins): Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions
---
# Architecture
How Video.js players are structured — state, UI, media, and extensions
Video.js v10 separates player responsibilities into parts that work independently or together, so you can use as much or as little of Video.js as you need.
For the reasoning behind this design, see [Why Video.js?](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/why-videojs).
## State management
State is handled by a preset player component, which creates a central state store that all components can access. When you wrap your player in `VideoPlayer`, the components automatically connect to the state.
```tsx
{/* All components inside automatically connect to state */}
```
You can access state and actions from anywhere within `VideoPlayer` with the [`usePlayer` hook](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-player).
- [Learn more about state and actions](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features)
## User interface
Use a prebuilt **skin** or build your own from the individual **UI components**.
### Skins
Skins are complete, pre-designed player UIs that package components and styles together. They give you a polished starting point, with a small set of CSS custom properties for common visual changes. They don’t try to cover every player with options.
```tsx
```
- [Learn more about skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins)
### UI components
If you want more control than a packaged skin offers, build your own UI from our components. Add, remove, and rearrange them to build the player you need.
```tsx
{/* ... */}
```
Skin source is a practical foundation for custom UI because it provides the same styled components as the packaged version. See [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source) to add it to your project.
- [Learn more about UI components](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components)
- [Build your own component](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/build-your-own-component)
## Media
Media components are the components that actually display your media. They’re essentially “players with no UI”. They handle the video/audio rendering and expose a consistent API.
Media components can be format specific (HLS, DASH), service specific (YouTube, Vimeo, Mux), or use case specific (background video).
```tsx
```
- [Learn more about media](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/media-sources)
## Extensions
Extensions add behavior to a player without rendering UI or playing media themselves.
```tsx
```
An extension can provide behavior that a UI component controls: GoogleCast supplies the configurable Cast route, and [CastButton](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/cast-button) renders the control that starts and ends a session.
## Presets
**Presets** preconfigure the state, UI, and media for a specific use case. Extensions stay opt-in, so add them to a preset player when you need them.
The default presets are `@videojs/react/video` and `@videojs/react/audio`, covering the baseline set of controls you’d expect from the HTML `` and `` tags.
Beyond the defaults, presets target more specific use cases. The `/background` preset combines a media element with autoplay, mute, and loop built in, a skin with no controls, and only the features needed to power it.
You can use it from `@videojs/react/background`.
- [Learn more about presets](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets)
## Related pages
### Guides
- [Installation](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/react): Install Video.js packages and build an accessible, customizable video player with composable controls
- [Features](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features): The state and actions each feature adds to the player
- [Skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins): Packaged player designs that include both UI components and their styles.
- [Presets](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets): Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.
---
# Customize skins
Style a packaged Video.js skin or add 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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#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 | [Style skin source](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source). The `shadcn` CLI adds the skin source to your project so you can change it. |
## 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
```
| Property name | What it changes | Value | Example |
| --- | --- | --- | --- |
| `--media-accent-color` | Slider fills, highlighted controls and menu items, and primary actions | [``](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) | `#f5c518` |
| `--media-accent-text-color` | Text and icons shown on the accent color | [``](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) | `black` |
| `--media-border-color` | The hairline around the player | [``](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 | [``](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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/poster).
### 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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/poster).
Packaged skins do not provide settings for adding, removing, or rearranging controls, or for replacing built-in feedback and interactions. To make those changes, [add the source for the closest skin to your project](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source) and edit it directly.
## Style skin source
If a packaged skin is close to the interface you want, add its source to your project and edit it. The source contains the skin’s controls, layout, styles, and interactions.
Video.js publishes skin source in an installable catalog. The [`shadcn` CLI](https://ui.shadcn.com/docs/cli) adds that source to your project, whether you use React or HTML.
The selected skin is generally placed under `components/videojs/`, with shared controls and styles alongside it under `components/videojs`. The exact root follows the components alias in `components.json`. The CLI can also install package dependencies, update `components.json`, and add shared styles to your main CSS file.
> **Note**
>
> Commit your work before installing or updating source. You can then review every file the CLI adds or replaces.
### Add the source
The Shadcn installation guide handles project setup, lets you choose the skin and styling, and shows how to use the installed source in a working player.
- [Install Video.js with Shadcn](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/shadcn?framework=react): Add editable skin source and build a working React or HTML player
### Use the installed skin
The skin’s entry file is `components/videojs//skin.tsx`. 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` |
| Change default colors, surfaces, shadows, sizes, or motion across skins | `components/videojs/styles/themes/theme.css` |
| Change only the Minimal theme or one media preset | `components/videojs/styles/themes/minimal.css`, `components/videojs/styles/video/theme.css`, or `components/videojs/styles/audio/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.
The installed skin sets `data-theme` and `data-preset` on its `Container`. Keep those attributes when you replace `skin.tsx` or compose the installed UI components into a custom player. They select the theme and media-specific rules from the catalog you installed.
- **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 the skin source
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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins). To create a control instead of editing one, follow [Build your own component](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/build-your-own-component).
## Related pages
### Components
- [VideoSkin](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/video-skin): The video preset's default skin with the modern, frosted look
### Guides
- [Skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins): Packaged player designs that include both UI components and their styles.
- [Build your own UI component](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/build-your-own-component): Create custom player controls that read state, dispatch actions, and stay accessible.
---
# Why Video.js?
The open-source video player for React and HTML. Lightweight, accessible components built for performance and streaming.
Video.js is the open-source video player for the web. It makes web video easy, performant, accessible, and customizable.
Let’s dig into when you’d want to use Video.js, starting with the question we hear most…
## Why not ``?
The native `` tag is enough for a short clip that plays without controls. Once viewers control playback, the gaps show up quickly.
### Cross-browser inconsistency
Chrome, Safari, and Firefox each render the default `` controls differently. You can hide them, but you can’t deeply style or rearrange them. Building UI that matches your product means starting from scratch.

Chrome

Safari

Firefox
### Accessibility
The browser’s controls bring their own accessibility behavior, and it differs by browser. Once you replace them, accessibility is your job: ARIA roles and labels that follow player state, keyboard controls and shortcuts, focus management, screen reader announcements when playback changes, controls that work with touch, tooltips and menus that stay on screen, and respect for reduced-motion and contrast preferences. Video.js components and skins handle these by default, following the WAI-ARIA Authoring Practices.
- [Learn more about accessibility](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/accessibility)
### Player state
Custom controls need to know what the media is doing. Even something as simple as “playing” or “buffering” comes from several events, behaves differently across browsers, streaming engines, and services like YouTube, and has to reset when the source changes. Wiring that by hand is fragile, and in React it quickly leads to tangled effects and extra renders.
Video.js keeps playback state in one player store that every component reads. Components reflect state as data attributes such as `data-paused`, so your CSS follows the player without extra code, and controls a browser can’t support, such as picture-in-picture, hide themselves. In React, `usePlayer` with a selector re-renders a component only when the state it selects changes.
- [Learn more about the architecture](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/architecture)
### Video interactions
Video often involves more than an MP4 in `src`. Features like thumbnail previews, adaptive bitrate, quality selection, chapters, audio track switching, localized controls, error UI, live-streaming UI, AirPlay, and DRM are *possible* with the video element, but require complex wiring and careful work on maintainability and [accessibility](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/accessibility).
Video.js provides accessible, composable building blocks for these common playback and streaming features. Other integrations, including ads and emerging media formats, remain under development as version 10 matures.
### Streaming formats and sources
Behind features like adaptive bitrate and quality selection are streaming formats such as HLS and DASH. They split video into segments that a playback engine can select based on bandwidth and preferences. Choose the matching Video.js media component to play these formats across browsers while keeping the surrounding player state and UI consistent.
Of course, your video might not be coming from a `src` like that. It might be provided by a service. However, services like YouTube, Vimeo, and Mux each speak their own API. Video.js gives their media components a consistent interface, so changing providers doesn’t require rebuilding the player around them.
That boundary also gives us a path to future sources such as canvas-based MoQ playback and use cases such as animated GIF replacement without rebuilding the controls around them.
## Why Video.js?
Video.js is built at Mux by the teams behind Video.js, Plyr, Vidstack, and Media Chrome, with contributions from engineers across other player projects. Between us, our projects have served tens of billions of monthly video plays. Most of the choices on this page came from things we got wrong the first time, then the second, then the fifth. We’ve been supporting your edge cases for over a decade. Now we’re shipping the player we always wanted to build.
Let’s dig into some of the design principles that help explain why we built Video.js and why it may be the best choice for your project or team.
### Add only what you need
Most player libraries ship every feature in one bundle, so you carry code you don’t run. If your video doesn’t need a feature like DRM, why ship that code? Video.js turns features into independent, *composable* modules. You hand `createPlayer` the array you actually want, and what you don’t import doesn’t ship.
```tsx
import { createPlayer, playbackFeature, timeFeature } from '@videojs/react';
const { Player } = createPlayer({
features: [playbackFeature, timeFeature],
});
```
- [Learn more about features](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features)
Of course, you don’t have to think about every feature you’re going to need if you don’t want to. Pre-built feature bundles are still there if you’d rather not assemble the list by hand.
- [Learn more about presets](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets)
### Framework-native
Many player libraries wrap a single web component for every framework. That works, until you reach the seams: refs you can’t pass through, state that doesn’t reconcile, prop names that aren’t quite React or HTML. Video.js ships idiomatic APIs for its supported frameworks: React components and hooks for React, and custom elements and controllers for HTML.
The player feels like the rest of your app.
**React**
```tsx
import { VideoPlayer, Video, VideoSkin } from '@videojs/react/video';
import '@videojs/react/video/skin.css';
function MyPlayer() {
return (
);
}
```
**HTML**
```html
```
### Source you can change
Most player libraries draw a line between “configurable through props” and “fork the source.” Cross the line and you’re on your own. Video.js lets you add the files for any skin to your project: components in your framework’s language that you can read and change. The rest of the player keeps working underneath it.
We don’t want to cram every possible player into one configuration API. Packaged skins cover common visual changes. For everything else, add the skin source to your project and compose the UI you need.
- [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source)
### AI-native DX
Documentation aimed at human readers usually doesn’t help an agent. Video.js publishes an `llms.txt` index, ships every docs page as both HTML and Markdown, and has a dedicated guide for building with AI assistants. Drop the player into a Claude or Cursor session and the docs come along for the ride.
- [Build with AI](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/build-with-ai)
## Related pages
### Guides
- [Installation](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/react): Install Video.js packages and build an accessible, customizable video player with composable controls
- [Architecture](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/architecture): How Video.js players are structured — state, UI, media, and extensions
---
# Browser support
Browsers and rendering environments supported by Video.js 10, and what the stylesheets need from them
Video.js 10 supports the **latest two stable versions** of Chrome, Edge, Firefox, Safari, and Safari on iOS. This page shows the versions that means today, what the packaged skins need from a browser, and how to reach older ones.
## Browser baseline
The build reads the policy from a [browserslist](https://browsersl.ist) query in the repository, and this page resolves the same query when the docs are built:
*Supported browsers and the versions the support policy resolves to today*
| Browser | Versions |
| --- | --- |
| Chrome | 150 and 151 |
| Edge | 150 and 151 |
| Firefox | 153 and 154 |
| Safari | 26.5 and 26.6 |
| Safari on iOS | 26.5 and 26.6 |
These are the versions we test in and fix bugs for. We build directly on the web platform, with [custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements), [`@scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/@scope), [container queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries), and [anchor positioning](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_anchor_positioning), and we do not hold a feature back to keep older versions working. Older versions often work anyway:
In practice the packaged skins render in Chrome 120, Edge 120, Firefox 146, Safari 17.4, and Safari on iOS 17.4 and later. Those versions account for 89.2% of global web usage according to [caniuse-lite](https://github.com/browserslist/caniuse-lite) 1.0.30001810, and this figure updates when we update that data.
## CSS requirements
The packaged skins are generated CSS, and a handful of newer features hold a skin together. **Required** features have no fallback: without them the player shows no component styling, and `@scope` alone sets the floor. **Degrades** features lose one visual detail. **Has a fallback** features sit inside [`@supports`](https://developer.mozilla.org/en-US/docs/Web/CSS/@supports); anchor positioning falls back to positions computed in JavaScript.
The table reads the first fully supporting version of each feature from [caniuse-lite](https://github.com/browserslist/caniuse-lite) when the docs build, and feature names link to [caniuse.com](https://caniuse.com/). The **effective floor** is the newest required version in each column.
*First browser version that fully supports each CSS feature the packaged skins use, with the share of global web usage on supporting browsers. Feature names link to their caniuse.com support data. "Not supported" means the browser has no full support. Paired browsers share a column and show two values only when they differ. The effective floor row is the newest required version in each column.*
| Feature | Chrome and Edge | Firefox | Safari and iOS | Global support |
| --- | --- | --- | --- | --- |
| [`@scope`](https://caniuse.com/css-cascade-scope) Required. No component styling. | 118 | 146 | 17.4 | 90.0% |
| [`CSS nesting`](https://caniuse.com/css-nesting) Required. No component styling. | 120 | 117 | 17.2 | 90.7% |
| [`@layer`](https://caniuse.com/css-cascade-layers) Required. No component styling. | 99 | 97 | 15.4 | 95.3% |
| [`:has()`](https://caniuse.com/css-has) Required. Menu and slider focus states are lost. | 105 | 121 | 15.4 | 94.1% |
| [`@container`](https://caniuse.com/css-container-queries) Required. Controls do not adapt to player width. | 106 | 110 | 16 | 94.0% |
| [`Media query range syntax`](https://caniuse.com/css-media-range-syntax) Required. Large-screen sizing is lost. | 104 | 63 | 16.4 | 94.0% |
| [`:dir()`](https://caniuse.com/css-dir-pseudo) Required. Right-to-left layout is lost. | 120 | 17 | 16.4 | 91.4% |
| [`Relative color syntax`](https://caniuse.com/css-relative-colors) Degrades. Adaptive shadows are lost. | 131 | 133 | 18 | 85.7% |
| [`scrollbar-color and scrollbar-width`](https://caniuse.com/css-scrollbar) Degrades. Menus show default scrollbars. | 121 | 64 | 26.2 | 85.6% |
| [`backdrop-filter`](https://caniuse.com/css-backdrop-filter) Degrades. Surfaces lose their blur. | 76 / 17 | 103 | 9 | 95.7% |
| [`Anchor positioning`](https://caniuse.com/css-anchor-positioning) Has a fallback. Popups are positioned by JavaScript. | 125 | 147 | 26 | 84.1% |
| Effective floor | 120 | 146 | 17.4 | 89.2% |
A few features have no caniuse entry. [`oklch()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch) is required but older than the floor (Chrome 111, Firefox 113, Safari 15.4). [`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark), [relative colors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_colors/Relative_colors), [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/@property), and [`contrast-color()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/contrast-color) each degrade on their own; set `--media-accent-text-color` from [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins) if you support browsers without `contrast-color()`. [Firefox ESR](https://www.mozilla.org/en-US/firefox/enterprise/) releases older than 146 lack `@scope`, so the skins render unstyled there.
The JavaScript has a lower floor: ES2022 syntax, with newer APIs feature-detected, so it runs in Chrome 102, Firefox 112, and Safari 16.4 or later. The stylesheet decides whether an older browser shows a working player.
### Support older browsers
To reach browsers below the floor, recompile the skin stylesheet with fallbacks. Only a stylesheet your build processes can be recompiled.
Skins are stylesheets you import, such as `@videojs/react/video/skin.css`, so your bundler’s CSS pipeline already sees them and nothing else changes.
[lightningcss](https://lightningcss.dev/transpilation.html) and [postcss-preset-env](https://preset-env.cssdb.org/) both read a browserslist query and add what those browsers lack: they flatten nesting and rewrite `:dir()`, range media queries, `light-dark()`, and `oklch()` in ordinary declarations, and add vendor prefixes. Neither rewrites `@scope` or `:scope`, so a small plugin flattens each block into descendant selectors prefixed with [`:where(root)`](https://developer.mozilla.org/en-US/docs/Web/CSS/:where), which adds no specificity. The PostCSS version, picked up by Vite, Next.js, and most bundlers from `postcss.config.mjs`:
```bash
npm install --save-dev postcss postcss-preset-env postcss-selector-parser
```
**postcss.config.mjs**
```js
import presetEnv from 'postcss-preset-env';
import selectorParser from 'postcss-selector-parser';
/** Rewrite `@scope () { … }` into descendant selectors that older browsers understand. */
function flattenScope() {
const rewrite = (selector, root) =>
selectorParser((selectors) => {
selectors.each((sel) => {
let referencesRoot = false;
sel.walk((node) => {
if (node.type === 'nesting' || (node.type === 'pseudo' && node.value === ':scope')) {
node.replaceWith(selectorParser.string({ value: root }));
referencesRoot = true;
}
});
if (!referencesRoot) {
sel.prepend(selectorParser.combinator({ value: ' ' }));
sel.prepend(selectorParser.string({ value: `:where(${root})` }));
}
});
}).processSync(selector);
return {
postcssPlugin: 'flatten-scope',
OnceExit(css) {
const scopes = [];
css.walkAtRules('scope', (atRule) => scopes.push(atRule));
// Innermost first, so a nested scope is flattened before its parent prefixes it.
for (const atRule of scopes.reverse()) {
const match = /^\(\s*(.+?)\s*\)\s*$/.exec(atRule.params);
if (!match || /\)\s*to\s*\(/.test(atRule.params)) continue;
atRule.walkRules((rule) => {
rule.selectors = rule.selectors.map((selector) => rewrite(selector.trim(), match[1]));
});
atRule.replaceWith(atRule.nodes);
}
},
};
}
flattenScope.postcss = true;
export default {
plugins: [flattenScope(), presetEnv({ browsers: 'baseline widely available', stage: 2 })],
};
```
The result renders in Chrome 111, Firefox 121, and Safari 16.4 or later, the floor [Tailwind CSS 4 documents](https://tailwindcss.com/docs/compatibility#browser-support), because `:has()`, `@container`, `@layer`, and `color-mix()` have no fallback. Flattening `@scope` trades scope proximity for source order; the packaged skins never nest a component inside itself, so the output matches. Run `npx browserslist "baseline widely available"` to see what the query resolves to today, or pick another query for your audience.
## Rendering contexts
### WebViews
A WebView is a browser engine embedded inside a native app. WebViews on iOS ([WKWebView](https://developer.apple.com/documentation/webkit/wkwebview)) and Android ([Android WebView](https://developer.android.com/reference/android/webkit/WebView)) can behave differently from the full browser; autoplay policies, fullscreen APIs, and hardware acceleration can vary.
Video.js 10 targets standard browser environments. If you embed a player inside a native app, test it on each platform and WebView version you support.
### Progressive Web Apps
Installed Progressive Web Apps (PWAs) use the browser engine, but their standalone display mode and platform policies can affect fullscreen, media sessions, and other browser integration. Test playback both in a browser tab and in the installed app.
### Smart TVs and set-top boxes
TV platforms run embedded browsers with limited standards support. Video.js 10’s core is not tied to any specific platform, which makes future TV adapters possible, but TV is not a supported target today.
### Server-side rendering
Video.js components render valid markup on the server. Interactivity — state management, media playback, and event handling — requires the browser and kicks in after hydration.
## Related pages
### Guides
- [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins): Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions
- [Installation](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/react): Install Video.js packages and build an accessible, customizable video player with composable controls
- [Bundlers](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/bundlers): Bundler requirements for Video.js package exports, CSS, and wrapper libraries
---
# Build with AI
Install the Video.js skill and give AI coding agents version-matched docs for building and migrating players
The [Video.js skill](https://github.com/videojs/skills) gives coding agents the context they need to build, customize, debug, and migrate Video.js players. It teaches the agent how Video.js 10 is composed, then points it to documentation that matches the version installed in your project.
## AI Quickstart
Paste this prompt into your coding agent:
```
Install the Video.js skill using one method. In Codex, run `codex plugin marketplace add videojs/skills`, then `codex plugin add videojs@videojs`, and start a new session. In Claude Code, run `claude plugin marketplace add videojs/skills`, then `claude plugin install videojs@videojs`, and start a new session or run `/reload-plugins`. In VS Code or Cursor, install `https://github.com/videojs/skills` as a plugin from source. For another agent, run `npx skills add https://github.com/videojs/skills --skill videojs` and select the agent. Then use the Video.js skill when working on this project.
```
## Video.js Skill
The skill contains guidance and Markdown references. It does not install Video.js, run background services, or connect to an account.
### Install the skill
#### Codex
Add the Video.js plugin marketplace, then install the plugin:
**Terminal**
```sh
codex plugin marketplace add videojs/skills
codex plugin add videojs@videojs
```
Start a new Codex session after installation.
#### Claude Code
Add the Video.js plugin marketplace, then install the plugin:
**Terminal**
```sh
claude plugin marketplace add videojs/skills
claude plugin install videojs@videojs
```
Start a new Claude Code session, or run `/reload-plugins` in the current session. You can invoke the skill directly with `/videojs:videojs`.
#### VS Code
Enable `chat.plugins.enabled`, run **Chat: Install Plugin From Source** from the Command Palette, and enter:
```text
https://github.com/videojs/skills
```
#### Cursor
Open **Customize**, select **Plugins**, choose **From GitHub Repository**, and enter:
```text
https://github.com/videojs/skills
```
#### Other coding agents
Use the open `skills` installer and select your agent when prompted:
**Terminal**
```sh
npx skills add https://github.com/videojs/skills --skill videojs
```
Project-local installation is the default. Add `-g` if you want the skill available in every project.
### Use the skill
Ask for the player you want to build or the problem you want to solve. For example:
> Add an HLS player with captions and a quality menu to the product page using Video.js.
> Play this Mux playback ID in our Next.js app with Video.js, with Mux Data turned on.
> Migrate this Video.js 8 embed to Video.js 10 in React.
The skill checks your framework and installation method before choosing player, skin, and media code. It also checks imports and playback setup against current documentation before handing the work back.
### How the skill finds current docs
The skill uses documentation in this order:
1. **Installed package docs.** `node_modules/@videojs/react/docs/llms.txt` and `node_modules/@videojs/html/docs/llms.txt` index the docs shipped with each package version. These files work offline and match the code in your project.
2. **Live docs.** If Video.js is not installed yet, or the project uses the CDN, the skill reads the framework index on videojs.org and opens only the pages needed for the task.
3. **Installed types.** If the docs are unavailable, the skill checks package exports and TypeScript declarations instead of guessing version-specific APIs.
This order matters because most model training data describes Video.js 8. Video.js 10 has a different component model, package structure, and installation flow.
### Troubleshoot
If your agent does not use the skill, start a new session or reload plugins, then ask it to use the Video.js skill explicitly. If it writes `videojs()`, `data-setup`, `registerPlugin`, or other Video.js 8 APIs, ask it to read the installed `llms.txt` before changing code.
Report problems with the skill in the [videojs/skills repository](https://github.com/videojs/skills/issues). Report package and documentation problems in [videojs/v10](https://github.com/videojs/v10/issues).
## Use the docs
You can still provide documentation directly when a tool cannot install skills.
### Copy one page
Each docs page has a **Copy page** menu. Copy the Markdown, open the `.md` version, or send the page to ChatGPT or Claude.
### Open a Markdown URL
Add `.md` to any docs URL. For this page, use:
```text
https://videojs.org/docs/framework/react/guides/build-with-ai.md
```
Each docs page also advertises its Markdown URL as an alternate format so compatible tools can discover it.
### Request Markdown
Request the normal docs URL with an `Accept: text/markdown` header:
**Terminal**
```sh
curl -H "Accept: text/markdown" \
https://videojs.org/docs/framework/react/guides/build-with-ai
```
### Start from llms.txt
[`videojs.org/docs/framework/react/llms.txt`](https://videojs.org/docs/framework/react/llms.txt) lists every React guide and reference page with a short description. Give the index to your tool, then load only the pages the task needs.
The `llms-full.txt` files contain the complete documentation corpus. Use them only when your tool requires one file because they are larger than most useful task contexts.
## Related pages
### Guides
- [Installation](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/react): Install Video.js packages and build an accessible, customizable video player with composable controls
- [Architecture](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/architecture): How Video.js players are structured — state, UI, media, and extensions
- [Build your own UI component](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/build-your-own-component): Create custom player controls that read state, dispatch actions, and stay accessible.
---
# v10 Roadmap
Timeline and milestones for Video.js v10 rebuild and the future of v8
Video.js v10 is a complete rebuild from the ground up, designed to be more modular, framework-flexible, and aligned with modern web development practices.
## Current versions
### Version 8
- Maintained with bug fixes and critical security patches only
- No new features will be planned
- Community contributions still welcome
- Documentation available at [legacy.videojs.org](https://legacy.videojs.org)
### Version 9
- Reserved only for urgent API-breaking changes that cannot be avoided
## March 2026: v10 Beta Release
Wider testing release to the community.
### Core feature parity target
- Basic control set (play, pause, seek, volume, fullscreen)
- Adaptive streaming support via existing community engines
- No plugin migrations yet, without plugin author contribution
### What to expect
- Close to stable, but API changes are still possible
- Intended for experimental adoption in real-world projects
- Developers encouraged to follow the [installation guide](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/react), try it out, and report issues
## September 2026: v10 Release Candidate
Feature-complete release ahead of GA.
### What to expect
- Close to stable. Remaining API changes are driven by feedback on the release candidate
- Intended for adoption in real-world projects
- Migration guides and reference documentation ready for review
## Fall 2026: v10 GA Release
**Stable release** of Video.js v10
### Feature targets
- Core feature parity with v8 in terms of fundamentals
- Feature parity with Media Chrome, Vidstack, Plyr, and Mux Player
- Community encouraged to begin full reintegration projects, following the migration guides for [Video.js 8](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-video-js-8), [Mux Player](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-mux-player), [Plyr](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr), and [Media Chrome](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-media-chrome)
- Plugin ecosystem migration begins in earnest
### Engine development focus
- Lightweight adaptive streaming
- MoQ (Media over QUIC) support
## Late-2026: Feature parity with v8 Contrib
**Extended feature parity** with Video.js “contrib” plugins:
- Ads integration
- Analytics support
- Further community plugin migration dependent on contributions
## End-of-life plan for Video.js v8
### Mid-2026
- v8/v9 moved to “video.js-legacy” repository and package
- Documentation preserved at [legacy.videojs.org](https://legacy.videojs.org)
- Hosted CDN copies will remain available
### 2027 and beyond
- Security patches only
- Community contributions de-prioritized
---
**Want to contribute?** Check out the [v10 repository on GitHub](https://github.com/videojs/v10) to get involved in the rebuild
## Related pages
### Guides
- [Why Video.js?](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/why-videojs): The open-source video player for React and HTML. Lightweight, accessible components built for performance and streaming.
- [Installation](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/react): Install Video.js packages and build an accessible, customizable video player with composable controls
---
# TypeScript
TypeScript version and module resolution requirements for Video.js packages
Video.js packages require **TypeScript 5.0 or newer**. TypeScript must also follow the import paths that each package publishes.
## TypeScript version
Video.js type files use syntax introduced in TypeScript 5.0. Older versions cannot read that syntax. The `skipLibCheck` option does not help because TypeScript must read a type file before it can skip checking it.
## Module resolution
Video.js packages define their supported import paths using [package exports](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/bundlers). Most web applications should use the following configuration. It makes TypeScript follow the same package rules as the bundler that builds the application:
**tsconfig.json**
```json
{
"compilerOptions": {
"module": "ESNext",
"moduleResolution": "bundler"
}
}
```
If Node.js runs files emitted directly by TypeScript, use `node16` for both `module` and `moduleResolution`, or use `nodenext` for both.
Do not use the older `node` setting, now called `node10`. It does not understand package exports and can report valid Video.js imports or types as missing.
## Errors from other dependencies
The older `node` setting allowed applications to import almost any file inside a dependency. Modern settings allow only the paths that dependency publishes. Changing the setting can therefore reveal an existing import into another package’s private files.
If the error names a package outside `@videojs/*`, update that dependency or use one of its supported import paths. A TypeScript `paths` override can be a temporary bridge when no supported replacement exists. Do not switch back to the older resolver because that also breaks Video.js type resolution.
## Related pages
### Guides
- [Installation](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/react): Install Video.js packages and build an accessible, customizable video player with composable controls
- [Bundlers](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/bundlers): Bundler requirements for Video.js package exports, CSS, and wrapper libraries
---
# Bundlers
Bundler requirements for Video.js package exports, CSS, and wrapper libraries
Before the browser runs your application, a bundler such as Vite combines its imports into files the browser can load. Your bundler must understand the import paths published by Video.js packages.
## Package exports
Each Video.js package has an `exports` field in its `package.json`. This field lists the import paths that applications and libraries can use, such as `@videojs/react/video` and `@videojs/react/live-video`.
If an older bundler reports that one of these paths is missing or not exported, upgrade the bundler before adding an alias that bypasses the package’s public API.
## Vite compatibility
Use Vite 4.1 or later; Video.js has been tested through Vite 8. Earlier versions can’t resolve exported stylesheets such as `@videojs/react/video/skin.css`.
React skins ship their stylesheet as a separate export: an application that renders `VideoSkin` from `@videojs/react/video` also imports `@videojs/react/video/skin.css`, so this limitation applies to every React application that uses a packaged skin.
## Externalize Video.js in a wrapper library
You can skip this section when building an application.
If you publish a library that expects its users to install Video.js separately, leave Video.js out of your library’s bundle. Rollup calls a dependency left out of the bundle **external**.
Rollup’s array form matches only the exact package name, so `external: ['@videojs/react']` misses imports such as `@videojs/react/video`.
Match the package name and everything below it instead:
**rollup.config.js**
```js
const videojsPeers = ['@videojs/react'];
export default {
external(id) {
return videojsPeers.some(
(packageName) => id === packageName || id.startsWith(`${packageName}/`)
);
}
};
```
Add every `@videojs/*` package your library imports directly to `videojsPeers` and list it in `peerDependencies`.
## Related pages
### Guides
- [Installation](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/react): Install Video.js packages and build an accessible, customizable video player with composable controls
- [TypeScript](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/typescript): TypeScript version and module resolution requirements for Video.js packages
---
# Content Security Policy
Allow the media, images, workers, and styles a Video.js player needs when your page enforces a Content Security Policy
Content Security Policy (CSP) limits which resources a page can load. Video.js uses the URLs you configure for media, posters, thumbnails, and captions. Some HLS renderers also create blob URLs or web workers, so your policy must allow those resources too.
## Allow player resources
- `media-src` must allow your media URLs.
- `img-src` must allow any poster or thumbnail image URLs.
- `connect-src` must allow HLS manifests, playlists, captions, and segment requests when using HLS playback.
- `media-src blob:` is required when using the HLS player variants, which use MSE-backed playback.
- `worker-src blob:` is required when using the `hls.js` player variants.
- `style-src 'unsafe-inline'` is required for some player UI.
## Recommended policy
```http
Content-Security-Policy:
script-src 'self';
style-src 'self' 'unsafe-inline';
img-src 'self' https: data: blob:;
media-src 'self' https: blob:;
connect-src 'self' https:;
worker-src 'self' blob:;
```
This policy assumes you bundle Video.js with your application or serve it from your own origin. If you load the player from a CDN, add that CDN’s origin to `script-src`.
Replace broad sources such as `https:` with the exact origins your player uses. Remove sources your deployment does not need, and keep `blob:` only where your selected HLS renderer requires it.
## Related pages
### Guides
- [Installation](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/react): Install Video.js packages and build an accessible, customizable video player with composable controls
---
# Features
The state and actions each feature adds to the player
Not every player needs to support every use case. To address this, Video.js has a concept of **features** — self-contained units of player functionality. Each one adds state properties and actions to the player. For example, “playback” adds `paused` and `play()`, “volume” adds `volume` and `setVolume()`, and so on.
## Feature bundles and presets
You probably don’t want to hand-pick every feature your player needs. A **feature bundle** groups the features needed for a specific use case into a single array.
For example, the `/video` preset configures `VideoPlayer` with `videoFeatures`, which bundles playback, volume, time, fullscreen, and more — everything a general video player needs:
```tsx
import { VideoPlayer, Video, VideoSkin } from '@videojs/react/video';
```
Feature bundles are usually paired with specific skins and media elements in a **preset**. To learn more about this, and the available presets, you’ll want to check out the presets guide.
- [Learn more about presets](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets)
## Individual features
If you’re not using presets, you can create a player that has individual features.
```tsx
import { createPlayer, playbackFeature, volumeFeature, timeFeature, controlsFeature } from '@videojs/react';
const { Player } = createPlayer({
features: [playbackFeature, volumeFeature, timeFeature, controlsFeature],
});
```
## Extended feature bundles
Since feature bundles are just an array of features under the hood, it doesn’t take much to extend one. For example, if you were using the `/background` preset and wanted a play button on your background video, you might add the playback feature.
```tsx
import { createPlayer, playbackFeature } from '@videojs/react';
import { backgroundFeatures } from '@videojs/react/background';
const { Player } = createPlayer({
features: [...backgroundFeatures, playbackFeature],
});
```
## Features inside components
You access feature state and actions through [`usePlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-player):
```tsx
// Subscribe to state (re-renders when selected values change)
const { paused, volume } = usePlayer((s) => ({
paused: s.paused,
volume: s.volume,
}));
// Call actions
const store = usePlayer();
store.play();
store.setVolume(0.8);
```
## Feature selectors
Each feature also has a pre-built selector (e.g. [`selectPlayback`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback), [`selectVolume`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-volume)) that returns just that feature’s state and actions:
```tsx
import { selectPlayback, usePlayer } from '@videojs/react';
const playback = usePlayer(selectPlayback);
playback?.play();
```
## Feature availability
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 | Meaning |
| --- | --- |
| `'available'` | Ready to use |
| `'unavailable'` | Could work, not ready yet |
| `'unsupported'` | Platform can never do this |
Components that depend on availability (like [`MuteButton`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mute-button), [`PiPButton`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/pip-button), and [`FullscreenButton`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/fullscreen-button)) handle the three states for you:
- **`unsupported`** — the button returns `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.
- **`disabled` prop** — an available button stays visible and focusable with `aria-disabled="true"` plus `data-disabled` for styling.
- **`available`** — fully interactive.
Use `data-disabled` to style the non-interactive state:
```css
.pip-button[data-disabled] {
opacity: 0.5;
cursor: not-allowed;
}
```
You can also check availability in JS:
**PiPControl.tsx**
```tsx
function PiPControl() {
const availability = usePlayer((s) => s.pipAvailability);
if (availability !== 'available') return null;
return ;
}
```
---
# Skins
Packaged player designs that include both UI components and their styles.
> **Note: New in version 10**
>
> In prior versions of Video.js, skins were CSS-only themes applied to the same set of default controls. In version 10 the concept of skins has been expanded to include the UI components, so each skin can be completely unique and only include the UI components it needs.
A skin wraps the media component and provides the player’s complete interface. It combines a specific set of UI components with the styles that arrange and present them.
## Packaged skins and skin source
When you choose a skin, you can import the packaged version or add its source to your project. It’s usually easiest to start with a packaged skin and add its source when you need more customization.
Packaged skins cover common visual changes through documented CSS custom properties. Packaged video skins also let you replace the poster. When you need more than that, add the skin source to your project and change the components and styles directly.
| Packaged skin | Skin source in your project |
| --- | --- |
| Single component | Many UI components |
| Documented CSS custom properties | Editable components and styles |
| Future design updates auto-applied by bumping the version | Future design updates manually applied, or intentionally ignored |
### Packaged skin
**Player.tsx**
```tsx
import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
import '@videojs/react/video/skin.css';
export function Player() {
return (
);
}
```
Don’t depend on elements, class names, or undocumented custom properties inside a packaged skin. They may change between releases.
- [Style a packaged skin](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-a-packaged-skin)
### Skin source in your project
The skin source contains the complete interface. You can add, remove, rearrange, or restyle any part of it.
- [Style skin source](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source)
### Custom interface
You can also build an interface without starting from a skin. In that model, you choose and arrange individual [UI components](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components) around the media. This takes more work, but it avoids inheriting a skin’s layout and interactions.
- [Build your own component](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/build-your-own-component)
## Skins, features, and presets
Each skin is built with specific [features](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features) in mind. For example, a video skin renders fullscreen and picture-in-picture controls. An audio skin doesn’t.
You’ll find a preconfigured player, its typed hook, a skin, and the matching feature bundle exported from the same path. We call these paths **presets**.
| Import | Description | Details |
| --- | --- | --- |
| `@videojs/react/video` | General-purpose video player preset with full playback controls. | **Feature bundle:** `videoFeatures`; **Features:** [playback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback), [playbackRate](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback-rate), [quality](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-quality), [audioTrack](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-audio-track), [volume](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-volume), [time](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-time), [source](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-source), [buffer](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-buffer), [fullscreen](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-fullscreen), [pip](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-pip), [remotePlayback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-remote-playback), [controls](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-controls), [textTrack](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-text-tracks), [error](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-error), [metadata](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-metadata); **Skins:** `` with `import '@videojs/react/video/minimal-skin.css';`, `` with `import '@videojs/react/video/skin.css';`; **Default media element:** `` |
| `@videojs/react/audio` | Audio-only player preset with playback and volume controls. | **Feature bundle:** `audioFeatures`; **Features:** [playback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback), [playbackRate](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback-rate), [volume](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-volume), [time](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-time), [source](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-source), [buffer](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-buffer), [error](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-error), [metadata](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-metadata); **Skins:** `` with `import '@videojs/react/audio/minimal-skin.css';`, `` with `import '@videojs/react/audio/skin.css';`; **Default media element:** `` |
| `@videojs/react/background` | Ambient background video preset with no user controls. | **Feature bundle:** `backgroundFeatures`; **Features:** –; **Skins:** `` with `import '@videojs/react/background/skin.css';`; **Default media element:** `` |
| `@videojs/react/live-audio` | Live audio player preset — `audio` minus playback rate, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveAudioFeatures`; **Features:** [playback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback), [volume](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-volume), [time](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-time), [source](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-source), [buffer](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-buffer), [error](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-error), [live](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-live), [metadata](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-metadata); **Skins:** `` with `import '@videojs/react/live-audio/minimal-skin.css';`, `` with `import '@videojs/react/live-audio/skin.css';`; **Default media element:** `` |
| `@videojs/react/live-video` | Live video player preset — `video` minus playback rate, quality selection, and audio-track selection, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveVideoFeatures`; **Features:** [playback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback), [volume](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-volume), [time](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-time), [source](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-source), [buffer](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-buffer), [fullscreen](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-fullscreen), [pip](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-pip), [remotePlayback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-remote-playback), [controls](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-controls), [textTrack](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-text-tracks), [error](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-error), [live](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-live), [metadata](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-metadata); **Skins:** `` with `import '@videojs/react/live-video/minimal-skin.css';`, `` with `import '@videojs/react/live-video/skin.css';`; **Default media element:** `` |
- [Read about presets](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets)
---
# Presets
Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.
A **preset** packages what you need for a specific player use case. It can include special [state management](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features), one or more [skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins) for UI, and specific media elements. Instead of assembling these pieces individually, you pick a preset that matches what you’re building.
For example, the `@videojs/react/background` preset includes a media element with autoplay, mute, and loop built in, a skin with no controls, and just the features needed to power them:
**App.tsx**
```tsx
import { BackgroundVideo, BackgroundVideoPlayer, BackgroundVideoSkin } from '@videojs/react/background';
import '@videojs/react/background/skin.css';
function Hero() {
return (
);
}
```
## Available presets
The default presets are `/video` and `/audio`. These cover the baseline controls you’d expect from the HTML `` and `` tags. Beyond the defaults, presets target more specific use cases — the `/background` preset, for example, needs layout but not controls. Over time we’ll add more: short-form players, podcast players, TV streaming players, and others.
| Import | Description | Details |
| --- | --- | --- |
| `@videojs/react/video` | General-purpose video player preset with full playback controls. | **Feature bundle:** `videoFeatures`; **Features:** [playback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback), [playbackRate](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback-rate), [quality](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-quality), [audioTrack](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-audio-track), [volume](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-volume), [time](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-time), [source](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-source), [buffer](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-buffer), [fullscreen](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-fullscreen), [pip](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-pip), [remotePlayback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-remote-playback), [controls](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-controls), [textTrack](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-text-tracks), [error](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-error), [metadata](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-metadata); **Skins:** `` with `import '@videojs/react/video/minimal-skin.css';`, `` with `import '@videojs/react/video/skin.css';`; **Default media element:** `` |
| `@videojs/react/audio` | Audio-only player preset with playback and volume controls. | **Feature bundle:** `audioFeatures`; **Features:** [playback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback), [playbackRate](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback-rate), [volume](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-volume), [time](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-time), [source](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-source), [buffer](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-buffer), [error](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-error), [metadata](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-metadata); **Skins:** `` with `import '@videojs/react/audio/minimal-skin.css';`, `` with `import '@videojs/react/audio/skin.css';`; **Default media element:** `` |
| `@videojs/react/background` | Ambient background video preset with no user controls. | **Feature bundle:** `backgroundFeatures`; **Features:** –; **Skins:** `` with `import '@videojs/react/background/skin.css';`; **Default media element:** `` |
| `@videojs/react/live-audio` | Live audio player preset — `audio` minus playback rate, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveAudioFeatures`; **Features:** [playback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback), [volume](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-volume), [time](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-time), [source](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-source), [buffer](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-buffer), [error](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-error), [live](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-live), [metadata](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-metadata); **Skins:** `` with `import '@videojs/react/live-audio/minimal-skin.css';`, `` with `import '@videojs/react/live-audio/skin.css';`; **Default media element:** `` |
| `@videojs/react/live-video` | Live video player preset — `video` minus playback rate, quality selection, and audio-track selection, plus the live feature, with a skin that swaps the time slider and time displays for a Live button. | **Feature bundle:** `liveVideoFeatures`; **Features:** [playback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback), [volume](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-volume), [time](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-time), [source](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-source), [buffer](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-buffer), [fullscreen](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-fullscreen), [pip](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-pip), [remotePlayback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-remote-playback), [controls](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-controls), [textTrack](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-text-tracks), [error](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-error), [live](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-live), [metadata](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-metadata); **Skins:** `` with `import '@videojs/react/live-video/minimal-skin.css';`, `` with `import '@videojs/react/live-video/skin.css';`; **Default media element:** `` |
## What’s in a preset
Each React preset exports a named, preconfigured player component and typed `usePlayer` hook, plus the building blocks needed to extend its features, add its skin source to your project, or swap its media element:
- **Player** — A player component named for the preset, such as `VideoPlayer`, already configured with the preset’s feature bundle.
- **Typed hook** — A `usePlayer` hook whose state and actions match the preset.
- **Feature bundle** — An array of [features](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features) that define the player’s state and actions. For example, the video feature bundle includes playback, volume, time, fullscreen, and more.
- **Skins** — Pre-built UIs designed for that feature bundle. For example, a video skin renders fullscreen and PiP controls because the video feature bundle includes those features. An audio skin doesn’t.
- **Media element** — A media component suited to the use case. For example, the background video element bakes in autoplay, mute, and loop.
These parts aren’t equally tied together. Skins depend tightly on their feature bundle — a skin expects specific features to exist. Media elements are more interchangeable — you can swap in an HLS or DASH provider without changing your skin or features.
## Customizing a preset
You can customize a preset in three ways: extend its feature bundle, add its skin source to your project, or swap its media element.
### Extend the feature bundle
Add features to a preset’s feature bundle to enable new functionality. For example, adding playback controls to a background video:
**App.tsx**
```tsx
import { Container, createPlayer, playbackFeature, PlayButton } from '@videojs/react';
import { backgroundFeatures, BackgroundVideo } from '@videojs/react/background';
const { Player } = createPlayer({
features: [...backgroundFeatures, playbackFeature],
});
function Hero() {
return (
);
}
```
### Skin source
If a preset’s skin is close but not quite right, [add its source to your project](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source) and customize its components and styles.
### Swap the media element
A preset’s default media element is just the starting point. You can replace it with any compatible media provider. For example, using an HLS source with the video preset:
```tsx
```
---
# UI components
How Video.js UI components use focused elements, data attributes for state, and compound composition.
UI components are controls like buttons, sliders, and time displays.
Visible UI components render at most one HTML element, taking inspiration from projects like [shadcn/ui](https://ui.shadcn.com/) and [Base UI](https://base-ui.com/). This approach gives you control over styling and behavior while handling the complex interactions for you. State-only components render no markup, and controls can skip rendering when their feature is unavailable.
Individual controls provide interaction, accessible names, and state. You add their visible text or icons and CSS. Sliders also need the child elements and styles shown on their reference pages.
## Where to put your components
UI components can go anywhere inside a [``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/player).
However, you should consider placing your components in ``. Components in `` will go fullscreen with the player, respond to user activity, and more.
- [Read more about ``](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/player-container)
## Styling and customization
For components you add yourself, use the documented props, state `data-*` attributes, and CSS custom properties. Add your own `className` when you need a selector.
### The `render` prop
The `render` prop is the primary customization mechanism. It accepts a function that receives `props` and `state`, and returns your element. The `props` object includes event handlers, ARIA attributes, data attributes, and a ref — always spread `{...props}` to keep everything working:
```tsx
import { PlayButton } from '@videojs/react';
import { PauseIcon, PlayIcon } from '@videojs/react/icons';
(
{state.paused ? : }
)}
/>
```
`className` and `style` also accept functions of state for dynamic styling without a full render prop:
```tsx
state.paused ? 'btn btn--paused' : 'btn btn--playing'
}
/>
```
### Data attributes and CSS custom properties
Components reflect player state as `data-*` attributes on their element. For example, `data-paused` or `data-volume-level="high"`.
This lets you style state changes in pure CSS:
```css
/* Show/hide icons based on play state */
.play-icon { display: none; }
.pause-icon { display: none; }
button[data-paused] .play-icon { display: inline; }
button:not([data-paused]) .pause-icon { display: inline; }
```
Each component’s reference page documents its full set of data attributes.
Some components also expose **CSS custom properties** for continuous values like fill percentage and pointer position. Sliders, for example, set `--media-slider-fill` and `--media-slider-pointer`. See individual component reference pages for specifics.
## Compound components
Complex interactions are split into composable parts. A parent manages shared state while children consume it. Each visible part owns at most one element.
Compound components use dot notation off a shared namespace:
```tsx
```
---
# Accessibility
How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player
Video.js is built with accessibility in mind so your player can reach the widest possible audience.
Here are some of the accessibility aspects we consider. You should consider them too if you’re performing deeper customization.
## Standards we target
- [**WAI-ARIA 1.2**](https://www.w3.org/TR/wai-aria-1.2/) defines roles, states, and properties that [assistive technologies](https://www.w3.org/WAI/people-use-web/tools-techniques/) use to understand controls.
- [**WCAG 2.2**](https://www.w3.org/TR/WCAG22/) provides success criteria for perceivable, operable, understandable, and robust web content.
- [**CVAA**](https://www.fcc.gov/consumers/guides/21st-century-communications-and-video-accessibility-act-cvaa) is a U.S. federal law requiring closed captioning and accessible controls for video content.
- [**ADA**](https://www.ada.gov/) is a U.S. civil rights law that prohibits disability discrimination. Courts increasingly apply it to websites, including video players.
- [**European Accessibility Act**](https://eur-lex.europa.eu/eli/dir/2019/882/oj) applies across the EU from June 28, 2025, and covers services such as e-commerce and audiovisual media. [**EN 301 549**](https://www.etsi.org/human-factors-accessibility/en-301-549-v3-the-harmonized-european-standard-for-ict-accessibility) is the European standard for meeting it, and it incorporates WCAG.
These standards and laws are listed for context, not as legal advice. Check which ones apply to your product.
## ARIA roles and labels
Components set ARIA roles and attributes automatically. For example, sliders render with `role="slider"` and value attributes, buttons update their `aria-label` based on player state, and decorative elements like time separators are hidden with `aria-hidden="true"`.
Built-in labels are translated. See [Internationalize the player](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/internationalization) to add or switch locales, and verify that labels are contextually correct for your content. Each component’s reference page documents the attributes it sets.
Tooltips are visual only. They are not linked to their trigger with `aria-describedby`, so a custom trigger needs its own accessible name. Built-in media buttons already have one.
## Keyboard interaction
All interactive components support keyboard control. For example, buttons activate with Enter and Space, sliders respond to Arrow keys, Home, End, and Page Up/Page Down, and popovers close with Escape. Each component’s reference page lists its full keyboard support. We follow the patterns in the [WAI-ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/).
Player-wide shortcuts, such as Space to play or M to mute, and tap gestures come from hotkey and gesture components. The skins ship a full set, and custom UI declares its own. See [Add keyboard shortcuts and gestures](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/keyboard-shortcuts).
## Focus management
Interactive elements are focusable when enabled and leave the [tab order](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) when disabled. Popover triggers link to their popups with `aria-controls` and `aria-expanded`. Menus and popovers close when focus moves away.
Dialogs move focus inside when they open, keep Tab within the dialog, and make the content behind them inert. Closing a dialog returns focus to its trigger, or to the element that had focus before it opened.
The player container is focusable and labeled: it takes `role="group"`, `tabindex="0"`, and an `aria-label` you can override. Keyboard users can tab to the player as a whole, and screen readers announce it as a named group.
## Status announcements
The player announces confirmed state changes through a visually hidden live region (`role="status"`), so screen reader users hear when playback starts or pauses, captions turn on or off, fullscreen, picture-in-picture, playback rate, or volume change, and where a seek lands.
Announcements follow confirmed state from the player store rather than requested changes, so routine time updates never reach the live region. Rapid volume and seek changes are grouped into a single announcement, and the player stays quiet while one of its sliders has focus, since the slider already announces its own value. The skins include the [status announcer](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/status-announcer). A custom layout needs to add it. State the store tracks is covered once it’s there; a custom control that tracks its own state needs its own live region.
## Captions and subtitles
The [text tracks feature](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-text-tracks) supports captions and subtitles. Closed captions in the U.S. are governed by the [FCC](https://www.fcc.gov/) under the [CVAA](https://www.fcc.gov/consumers/guides/21st-century-communications-and-video-accessibility-act-cvaa), which requires both captioning and viewer control over caption appearance (font, size, color, opacity, and edge style). Non-compliance carries legal risk.
Video.js leaves caption rendering to the browser, and you style cues with the `::cue` pseudo-element. It doesn’t include a menu for caption appearance, so viewers rely on the caption preferences their browser and operating system provide. The [WebKit Caption Display Settings explainer](https://github.com/WebKit/explainers/tree/main/CaptionDisplaySettings) tracks how browsers are bringing these preferences into the web platform. See [Show captions and subtitles](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/captions) to add tracks and a captions control.
## Transcripts and audio description
Captions don’t cover every viewer. [WCAG 2.2](https://www.w3.org/WAI/WCAG22/Understanding/audio-description-or-media-alternative-prerecorded) also expects audio description or a text alternative for prerecorded video. A transcript can live inside the [player](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/player) but outside its container, so it reads player state without going fullscreen with the video. When a stream includes a described audio track, an [audio track menu](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/audio-track-radio-group) lets viewers choose it.
## Color contrast
Skins respond to [`prefers-contrast: more`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-contrast) by increasing background opacity on overlays and controls, and to [`prefers-reduced-transparency: reduce`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-transparency) by raising baseline opacity so text stays readable over video.
Video is harder than most UI for contrast because the background is always changing. A control that passes checks over a dark frame can disappear over a bright title card. Automated tools won’t catch this, so test your controls against light, dark, and mixed video content. Custom components should test against [WCAG 1.4.3 (contrast minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum) and [1.4.11 (non-text contrast)](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast).
## Touch targets
Skin controls size from `--media-scale-unit`, which defaults to `16px`, so they don’t grow with the user’s font size preference. Set it to `1rem` to scale with the document root font size. See [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#scale-from-the-document-font-size).
Skin buttons set [`touch-action: manipulation`](https://developer.mozilla.org/en-US/docs/Web/CSS/touch-action) to remove tap delay on touch devices, and sliders set `touch-action: none` so dragging doesn’t scroll the page. Skins use [`pointer: fine` and `pointer: coarse`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/pointer) to adapt transitions for mouse and touch input.
If you build custom controls, target at least 24x24 CSS pixels per [WCAG 2.5.8 (target size minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum). Larger is better on touch-first surfaces.
## Color scheme
The audio skins switch their palette for light and dark mode with [`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark), which follows the inherited [`color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme), not the user’s preference directly. Set `color-scheme: light dark` on the page or the player to follow the user’s setting. The video skins keep dark controls in both schemes; only their border follows it. See [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#set-the-color-scheme).
## Reduced motion
Skins respect [`prefers-reduced-motion`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) by simplifying or removing animations and transitions. Follow the same pattern in custom components.
That covers the controls, not the video. Video.js doesn’t pause or hide autoplaying video for reduced-motion users; your page decides that.
## Autoplay and moving video
[WCAG 2.2.2](https://www.w3.org/WAI/WCAG22/Understanding/pause-stop-hide) requires a way to pause, stop, or hide motion that starts automatically and lasts more than five seconds. A muted, looping hero video counts. Give it a pause control, or keep it short.
A purely decorative video should be hidden from assistive technology with `aria-hidden="true"` on its wrapper. If the video carries information, give it an accessible name and controls, and use a regular player. See [Add a background video](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/background-video) and [Autoplay](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/autoplay).
## Test with assistive technology
Automated tools catch markup issues but miss real usability problems. Test your player with a [screen reader](https://www.w3.org/WAI/people-use-web/tools-techniques/) ([VoiceOver](https://support.apple.com/guide/voiceover/welcome/mac) on macOS, [NVDA](https://www.nvaccess.org/about-nvda/) or [JAWS](https://www.freedomscientific.com/products/software/jaws/) on Windows) and keyboard-only navigation. Verify that every control is reachable, operable, and announces its purpose and state. The [WAI “Easy Checks”](https://www.w3.org/WAI/test-evaluate/preliminary/) are a good starting point.
## Further reading
The W3C WAI guides on [making audio and video media accessible](https://www.w3.org/WAI/media/av/) and [accessible media players](https://www.w3.org/WAI/media/av/player/) go deeper on everything covered here.
---
# Media sources
Set what a media element plays and how its engine plays it with the structured source property
Every media element takes a `src`. Elements that drive a playback engine also take `source`, a structured object that carries the URL alongside everything else about that source:
```tsx
```
## Three tiers, three homes
The shape answers one question: does this option describe the source, or how to play it?
| Tier | Home | Example |
| --- | --- | --- |
| Which source to play | `source.src`, or an element’s own identity fields | `src`, `MuxVideo`’s `playbackId` |
| How to interpret it | `source.type` | `'video/mp4'` |
| How Video.js plays it | `source`, at the top level | `preferPlayback`, `maxAutoResolution`, `capRenditionToPlayerSize` |
| How a specific engine behaves | `source.engine`, under that engine’s name | hls.js’s `maxBufferLength`, in `source.engine.hlsJs` |
| An extension’s own settings | that extension’s props | [Mux Data](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/mux-data), [GoogleCast](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/google-cast) |
`type` is worth reaching for when the URL lies about its contents. Video.js infers the content type from the file extension, so a manifest served from an extensionless or signed URL may need to say so explicitly:
```tsx
```
The legacy HLS spelling `application/x-mpegURL` is accepted as an alias, and matching is case-insensitive. An HLS source whose `type` isn’t recognized is handed to the browser as-is rather than to hls.js, which leaves quality and audio-track selection unavailable.
## `src` and `source` stay in sync
They are two views of the same thing, and writing either updates the other. Setting `source` derives `src`. Setting `src` replaces only the identity half and **keeps the rest, such as `type` and the engine options, intact**:
```tsx
```
A `sourcechange` event fires whenever `source` changes, from either direction.
## Assigning `source` replaces it
`source` is not merged. A new object is a fresh start, and keys you leave out are dropped:
```tsx
// later: type and preferPlayback are gone, because the new object omits them
```
## Equivalent sources cost nothing
Sources are compared **structurally**, not by reference. Reassigning an object with the same values is a no-op — no reload, and no engine teardown:
```tsx
// A fresh object literal on every render. Nothing reloads.
```
This is why you can write `source` inline. React hands the element a brand new object every render, and the element recognizes it as the same source. There’s no need to memoize it or spread the previous value to avoid clobbering anything.
Only a change to the engine options, `preferPlayback`, or the resolved content type recreates the playback engine.
## Engine options
Engine options live under `source.engine`, **namespaced by engine**. Each key there holds that engine’s own configuration object, handed over untouched — there’s no Video.js wrapper around it, so whatever the engine documents works:
| Key | Elements that read it | It holds |
| --- | --- | --- |
| `engine.hlsJs` | [HlsJsVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hlsjs-video), [MuxVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-video), [MuxAudio](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-audio) | an [hls.js config](https://github.com/video-dev/hls.js/blob/master/docs/API.md#fine-tuning) |
| `engine.nativeHls` | [NativeHlsVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/native-hls-video), and the three above whenever the browser plays the manifest | options for the browser’s own HLS support (today, [DRM](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/media-sources#licensing-one-engine-differently)) |
| `engine.dashJs` | [DashVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/dash-video) | [dash.js settings](https://cdn.dashjs.org/latest/jsdoc/module-Settings.html) |
| `engine.vimeo` | [VimeoVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/vimeo-video) | [Vimeo embed parameters](https://developer.vimeo.com/player/sdk/embed) |
| `engine.youtube` | [YouTubeVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/youtube-video) | [YouTube player parameters](https://developer.chrome.com/docs/youtube/iframe_api_reference#Parameters) |
| `engine.cloudflare` | [CloudflareVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/cloudflare-video) | [Stream player parameters](https://developers.cloudflare.com/stream/viewing-videos/using-the-stream-player/) |
| `engine.spotify` | [SpotifyAudio](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/spotify-audio) | [Spotify embed options](https://developer.spotify.com/documentation/embeds) |
| `engine.tiktok` | [TikTokVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/tiktok-video) | [TikTok player parameters](https://developers.tiktok.com/doc/embed-player) |
| `engine.twitch` | [TwitchVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/twitch-video) | [Twitch embed parameters](https://dev.twitch.tv/docs/embed/video-and-clips/) |
Naming the engine rather than using one generic key matters where an element has more than one to choose from. `HlsJsVideo` plays through hls.js or through the browser depending on the platform and `preferPlayback`, and only one of them runs — so a single source can describe both paths without either engine reading the other’s options.
hls.js reads its options when the engine is constructed, so changing them tears down the engine and builds a new one:
```tsx
```
dash.js takes settings on a running player, so `engine.dashJs` is applied in place and playback continues uninterrupted:
```tsx
```
Because `engine.dashJs` replaces rather than merges, dropping a key restores the dash.js default instead of leaving the old value behind.
### Options Video.js normalizes
Where an option means the same thing across engines, it sits on `source` itself rather than inside an engine’s namespace.
`preferPlayback` picks between [hls.js](https://github.com/video-dev/hls.js/) and the browser’s own HLS support:
```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
```
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
```
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
```
**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:
```tsx
```
Name every system you hold a license server for — which one gets used is the browser’s choice. `serverCertificateUrl` is the DRM server (application) certificate FairPlay requires; Widevine and PlayReady ignore it.
### What each path can license
The same `drm` reaches both playback paths, and how far it gets is the one thing worth knowing about each:
| Path | Key systems it negotiates | What Video.js does with `drm` |
| --- | --- | --- |
| hls.js (MSE) | FairPlay, Widevine, PlayReady | Hands it to hls.js as `drmSystems`, with `emeEnabled` switched on |
| The browser’s own HLS | FairPlay | Answers the element’s key requests itself: POSTs the CDM’s license request to `licenseUrl` and hands the response back |
So a source naming only Widevine plays through hls.js and cannot play on the native path — [NativeHlsVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/native-hls-video), or any HLS element the browser ends up playing the manifest for. Video.js says so in development, and encrypted media that gets there with no `com.apple.fps` license server fails with a `MEDIA_ERR_ENCRYPTED` error rather than hanging.
For Widevine on hls.js, Video.js asks for a hardware-backed CDM first, falling back to whatever robustness the browser offers, so content restricted to L1 devices plays where it can. Supplying your own `requestMediaKeySystemAccessFunc` replaces that entirely.
### Licensing one engine differently
An engine’s own `drmSystems` **replaces** `source.drm`, for that engine alone. Reach for it when one path licenses differently, or when you need more of [hls.js’s DRM configuration](https://github.com/video-dev/hls.js/blob/master/docs/API.md#drmsystems) than `drm` covers:
```tsx
```
It replaces rather than merges, so the FairPlay server above is gone as far as hls.js is concerned. `engine.nativeHls.drmSystems` does the same for the native path.
## Mux sources name a playback ID
[MuxVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-video) and [MuxAudio](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-audio) identify a source by `playbackId` rather than a URL, and derive `src` from it. Everything else works the same, engine options included:
```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:
```tsx
```
`MuxVideo` uses the storyboard itself, adding the thumbnail `` for you so hover previews work without extra markup. Live streams have no storyboard, so the track is dropped once the stream type is known, and signed playback without a matching storyboard token adds none.
### Mux signs DRM with a token
Mux serves FairPlay, Widevine, and PlayReady from URLs derived from a single license token, so `source.drm` takes that token in place of the license servers it would otherwise name. Mux fills the rest in for you, so protected media plays whichever path the browser takes:
```tsx
```
DRM playback is always signed, so a `playback.token` belongs alongside it — and `poster.token` / `storyboard.token` for the images. Each is scoped to a different audience, so they are four separate tokens rather than one reused four times. Sign them on your server; see [Mux’s DRM guide](https://www.mux.com/docs/guides/protect-videos-with-drm) for how.
A `drm.token` that isn’t scoped to DRM is ignored rather than sent, since the license request would be rejected. License servers named alongside the token win, key by key, for the systems Mux doesn’t license:
```tsx
```
`source.poster` gets no such treatment — it’s only data, and nothing applies it to the media. Both URLs are readable from `contentData`, keyed by what each one describes:
```ts
media.contentData;
// {
// poster: 'https://image.mux.com/PLAYBACK_ID/thumbnail.webp?time=12',
// storyboard: 'https://image.mux.com/PLAYBACK_ID/storyboard.vtt?format=jpg',
// }
```
It’s read-only and derived from `source`, so read it again after `sourcechange`. A key is missing when its URL can’t be built: no playback ID, or signed playback with no matching image token. Changing the URLs means changing the params they’re built from.
One more key arrives later. Mux publishes a small metadata document for each asset, and the media loads it alongside the stream, so `contentData.title` fills in with the asset’s title once it does — `contentdatachange` announces it. The player reads it as the fallback for its own title, so a Mux asset titled in the dashboard names itself without a `title` on the player. Any other entries the document carries ride along under their own keys. An untitled asset adds nothing.
`source.poster` takes the [full set of Mux image modifiers](https://www.mux.com/docs/guides/get-images-from-a-video), so a narrower still for a small viewport is a `width`:
```tsx
```
## Elements without engine options
[HlsVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hls-video) and [HlsAudio](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hls-audio) take `src` and the usual media props but expose no `source`. They run on our own playback engine, which does not accept configuration from the element yet.
## See also
- [HlsJsVideo element reference](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hlsjs-video)
- [MuxVideo element reference](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-video)
- [DashVideo element reference](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/dash-video)
---
# Autoplay
Start playback automatically and handle browser autoplay restrictions.
For the best chance of autoplay succeeding, start playback muted and enable inline playback. Autoplay is a request, not a guarantee: browsers can block it based on audio state, prior interaction with your site, browser settings, and platform policy.
## Recommended approach
Set autoplay, muted, and inline playback on the media element, and keep a manual play control available for when autoplay is blocked.
**App.tsx**
```tsx
import { Container, PlayButton } from '@videojs/react';
import { Video, VideoPlayer } from '@videojs/react/video';
export default function BasicUsage() {
return (
(
{state.ended ? 'Replay' : state.paused ? 'Play' : 'Pause'}
)}
/>
);
}
```
**App.css**
```css
.media-container {
position: relative;
}
.media-container video {
width: 100%;
aspect-ratio: 16 / 9;
}
.media-play-button {
position: absolute;
bottom: 10px;
left: 10px;
padding-block: 8px;
padding-inline: 20px;
color: black;
cursor: pointer;
background: rgba(255, 255, 255, 0.7);
border: 1px solid rgba(255, 255, 255, 0.3);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
```
## How it works
The `autoPlay`, `muted`, and `playsInline` props on [`Video`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/create-player) and similar media components pass through to the underlying media element. When the media element supports them, they’re applied, and playback is requested as soon as the media has enough data.
The [playback feature](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback) reflects the result in player state. When autoplay succeeds, `paused` becomes `false` and `started` becomes `true`. When the browser blocks autoplay, the player stays `paused: true` with `started: false`, and the [Play button](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/play-button) renders its play state. There is no separate autoplay failure event: a blocked autoplay looks like media that never started.
Calling `play()` from player state returns the native promise from the media element. When the browser blocks playback, that promise rejects with a `NotAllowedError`.
## Availability and constraints
- Autoplay can fail. Browsers decide per page load based on audio state, whether the user has interacted with your site before, browser settings, and platform policy.
- Muted autoplay is broadly allowed. Unmuted autoplay is blocked on first visit in most browsers; do not rely on it.
- Without inline playback, iPhone Safari opens the video in fullscreen when playback starts.
- Low-power mode and data-saver settings can block even muted autoplay. This is why the recommended approach keeps a manual play control.
- Programmatic volume control is unsupported on some platforms. The [volume feature](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-volume) exposes this as `volumeAvailability: 'available' | 'unavailable' | 'unsupported'`; iOS Safari reports `'unsupported'`, and `'unavailable'` means the feature hasn’t attached to a media element yet.
- This guide applies to media components that render a video element (Video, HlsJsVideo, DashVideo, MuxVideo, and the like). Embed components (YouTube, Vimeo, TikTok, Twitch) forward autoplay to the third-party player, which applies its own autoplay rules; muted and inline behavior varies by provider.
## Common variations
### Background video
Background video autoplays, loops, stays muted, and omits interactive controls. Use `HlsBackgroundVideo` instead of configuring these behaviors yourself: it applies them by default and streams an HLS source, picking one rendition that fits the screen for the whole session.
Install the SPF adapter with the React façade:
```bash
pnpm add @videojs/react @videojs/spf
```
```tsx
import { HlsBackgroundVideo } from '@videojs/react/media/hls-background-video';
export default function Hero() {
return ;
}
```
If you have a progressive MP4 or WebM file instead of an HLS stream, `BackgroundVideo` is the same component without the streaming engine. See [BackgroundVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/background-video) for opt-out props and sizing.
### Autoplay with sound
Do not rely on unmuted autoplay for a user’s first visit. Start playback from an explicit user action instead.
Call `play()` from the player store returned by [`usePlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-player):
```tsx
import { Container } from '@videojs/react';
import { usePlayer, Video, VideoPlayer } from '@videojs/react/video';
function StartPlaybackButton() {
const store = usePlayer();
return (
store.play()}>
Play video
);
}
export default function App() {
return (
);
}
```
Because playback starts from a user gesture, the browser allows it unmuted.
## Troubleshooting
### Playback does not start
Confirm that:
- The media is muted.
- Inline playback is enabled.
- The source loads (check the network panel).
- A manual play control is available as a fallback.
If autoplay is blocked, the player stays paused and the Play button remains in its play state; there is no error state to handle.
### The video opens fullscreen on iPhone
Enable inline playback with the `playsInline` prop on the media component.
### The video starts without sound
Expected with muted autoplay. Let the user unmute through a [Mute button](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mute-button) or [Volume slider](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/volume-slider) rather than unmuting programmatically; programmatic volume changes are unsupported on some platforms.
## Related pages
### Components
- [PlayButton](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/play-button): Accessible play/pause button with keyboard support and customizable rendering
- [MuteButton](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mute-button): Accessible mute/unmute button with keyboard support and volume state reflection
- [BackgroundVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/background-video): Decorative background video element with automatic muting and looping
- [Controls](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/controls): Container component for composing and auto-hiding video player controls on user interaction
### API
- [Playback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback): Play/pause state and actions for the player store
- [Volume](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-volume): Volume level and mute state for the player store
- [usePlayer](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-player): Hook to access the player store from within a Player
### Guides
- [Features](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features): The state and actions each feature adds to the player
- [Browser support](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/browser-support): Browsers and rendering environments supported by Video.js 10, and what the stylesheets need from them
---
# Automatically show and hide controls
Show controls while the user is active, hide them during playback, and toggle them by touch.
> **Note**
>
> Using a pre-built [skin](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins)? 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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components).
## Recommended approach
Wrap your control UI in [Controls](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/controls). It reads controls visibility from player state, so the whole control bar shows and hides as one unit.
**App.tsx**
```tsx
import { Container, Controls, createPlayer, PlayButton, Time } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';
const { Player } = createPlayer({ features: videoFeatures });
export default function BasicUsage() {
return (
{state.paused ? 'Play' : 'Pause'} }
/>
);
}
```
**App.css**
```css
.media-container {
position: relative;
}
.media-container video {
width: 100%;
}
.media-controls {
position: absolute;
inset: 0;
display: flex;
align-items: flex-end;
padding: 12px;
pointer-events: none;
transition: opacity 0.25s;
}
.controls-backdrop {
position: absolute;
inset: 0;
pointer-events: none;
background: linear-gradient(to top, rgba(0, 0, 0, 0.45), transparent 45%);
opacity: 1;
transition: opacity 0.35s;
}
.controls-backdrop:not([data-visible]),
.media-controls:not([data-visible]) {
opacity: 0;
}
.controls-group {
display: flex;
align-items: center;
justify-content: space-between;
width: 100%;
pointer-events: auto;
}
.time {
display: inline-flex;
gap: 4px;
align-items: center;
padding-block: 8px;
padding-inline: 16px;
font-size: 14px;
color: black;
background: rgba(255, 255, 255, 0.75);
border: 1px solid rgba(255, 255, 255, 0.25);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
.button {
padding-block: 8px;
padding-inline: 16px;
font-size: 14px;
color: black;
cursor: pointer;
background: rgba(255, 255, 255, 0.75);
border: 1px solid rgba(255, 255, 255, 0.25);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
```
## How it works
The [controls feature](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-controls) tracks activity on the player container:
- `userActive` is `true` while the user interacts — pointer movement, keyboard input, or focus — and flips to `false` after two seconds of inactivity.
- `controlsVisible` derives from activity and playback: controls stay visible while paused or while a remote playback session is connecting or connected, regardless of idle state.
- `toggleControls()` flips visibility, for wiring to custom triggers.
On touch devices, a tap on the media toggles the controls instead of relying on pointer movement, and mid-gesture movement doesn’t flicker visibility.
The feature needs the player container for activity tracking; without a container it stays inactive and warns in development.
## Availability and constraints
- Activity tracking listens on the player container, so controls placed outside it don’t keep the player “active” — put control UI inside the container.
- Keyboard focus counts as activity: controls stay reachable for keyboard and assistive-technology users while focus is inside them.
- Touch and mouse behave differently by design — mouse movement shows controls, touch requires a tap. Test both.
- The idle delay is fixed at two seconds.
## Common variations
### Always-visible controls
Set `visibility="always"` on [Controls](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/controls). The controls stay visible and report the user as active while the feature keeps tracking activity for anything else that needs it. The packaged audio skins use this mode.
```tsx
...
```
### Custom show/hide styling
Controls hide by state, so you own the transition. Style the visible and hidden states in CSS — fade, slide, or scale — driven by the component’s rendered state rather than re-implementing the idle timer.
## Troubleshooting
### Controls never hide
The media is paused (controls intentionally stay visible), a remote playback session is active, an open menu or popover holds a controls lock, or something keeps triggering activity — for example a focused element inside the container receiving repeated events.
### Controls don’t come back on touch
A tap on the media toggles controls. If a custom overlay covers the media and swallows pointer events, taps never reach the container; let pointer events pass through decorative overlays.
### Controls flicker on Android while tapping
Use the skin gestures (`tap` with the `toggleControls` action) rather than adding your own tap handlers next to the built-in behavior; competing handlers invert each other. See [Add keyboard shortcuts and gestures](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/keyboard-shortcuts).
## Related pages
### Components
- [Controls](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/controls): Container component for composing and auto-hiding video player controls on user interaction
- [Container](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/player-container): The player's visual and interaction surface for layout, fullscreen, focus, and user activity.
### API
- [Controls](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-controls): User activity and controls visibility state for the player store
### Guides
- [Add keyboard shortcuts and gestures](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/keyboard-shortcuts): Add keyboard shortcuts, tap and double-tap gestures, and on-screen feedback for input actions.
- [Accessibility](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/accessibility): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player
---
# 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 `` element, or a loading placeholder. The skin renders your image instead of its own.
4. **Keep it working after [adding the skin source to your project](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source).** 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 (
);
}
```
## 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 (
);
}
```
If you use a ready-made skin, it includes [Poster](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/poster) 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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-metadata) 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 ` ` 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 (
src ? : null
}
>
);
}
```
## 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 (
src ? (
) : null
}
>
);
}
```
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 (
(
)}
>
);
}
```
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 after adding skin source
Adding the skin source to your project changes nothing about the first two approaches: the player’s `poster`, or the poster the media provides, still reaches the [Poster](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/poster) component your skin renders.
`Poster.Root` owns visibility and loading state. `Poster.Image` renders the image 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 the image’s `render` prop:
```tsx
(
)}
/>
```
## 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 pages
### Components
- [Poster](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/poster): Poster image component that displays a thumbnail until video playback starts
### API
- [Metadata](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-metadata): Resolved title and poster values for the player store
### Guides
- [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-a-packaged-skin): Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions
- [Build your own UI component](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/build-your-own-component): Create custom player controls that read state, dispatch actions, and stay accessible.
---
# Show captions and subtitles
Show captions and subtitles, and let users turn them on and pick a language.
> **Note**
>
> Using a pre-built [skin](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins)? 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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components).
## Recommended approach
Add WebVTT tracks as `` children of the media element, and give users a [CaptionsButton](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/captions-button) to toggle them.
**App.tsx**
```tsx
import { CaptionsButton, Container } from '@videojs/react';
import { Video, VideoPlayer } from '@videojs/react/video';
export default function BasicUsage() {
return (
(
{state.subtitlesShowing ? 'Captions Off' : 'Captions On'}
)}
/>
);
}
```
**App.css**
```css
.media-container {
position: relative;
}
.media-container video {
width: 100%;
aspect-ratio: 16 / 9;
}
.media-captions-button {
position: absolute;
bottom: 10px;
left: 10px;
padding-block: 8px;
padding-inline: 20px;
color: black;
cursor: pointer;
background: rgba(255, 255, 255, 0.7);
border: 1px solid rgba(255, 255, 255, 0.3);
border-radius: 9999px;
backdrop-filter: blur(10px);
}
```
## How it works
The [text track feature](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-text-tracks) mirrors the media element’s `textTracks` into player state:
- `textTrackList` holds every track with its `id`, `kind`, `label`, `language`, and `mode`.
- `subtitlesShowing` is `true` when any caption or subtitle track is showing.
- `toggleSubtitles(forceShow?)` shows or hides all caption and subtitle tracks.
- `selectSubtitlesTrack(id)` shows one track and disables the rest; pass `'off'` to disable all.
Tracks don’t have to come from `` elements: tracks that streaming media exposes (for example in-manifest HLS captions) appear in `textTrackList` the same way.
The browser renders the cues. Style them with the `::cue` pseudo-element.
## Availability and constraints
- Captions availability is `'unavailable'` until the media has at least one caption or subtitle track; caption controls render nothing in that case.
- Cues load asynchronously. A track appears in `textTrackList` before its cues are parsed, so cue-driven UI fills in when the track finishes loading.
- Cross-origin track files require CORS: serve the VTT with CORS headers and set `crossOrigin` on the media element.
- Track selection UIs identify tracks by `label` and `language`; give every track both.
- `default` on a `` makes the browser show it initially.
## Common variations
### Language selection menu
For multiple languages, render a menu instead of a toggle.
`useCaptionsOptions` provides the option list (including “Off”), the selected value, and availability:
```tsx
import { Menu, useCaptionsOptions } from '@videojs/react';
function CaptionsMenu() {
const captions = useCaptionsOptions();
if (captions?.state.availability !== 'available') return null;
return (
}>Captions
{captions.options.map((option) => (
{option.label}
))}
);
}
```
See the [CaptionsRadioGroup](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/captions-radio-group) reference for the complete pattern.
## Troubleshooting
### Captions don’t appear
Confirm that:
- The track `kind` is `captions` or `subtitles`.
- The VTT file loads (check the network panel for the track request).
- The track is enabled: `default` on the track element, a CaptionsButton toggle, or `toggleSubtitles(true)`.
### Captions work locally but not in production
The track file is served from another origin without CORS headers. Serve it with `Access-Control-Allow-Origin` and set `crossOrigin` on the media element.
### The selection menu is empty
The media has no caption or subtitle tracks, so captions availability is `'unavailable'`. For streaming sources, confirm the manifest actually declares text tracks.
## Related pages
### Components
- [CaptionsButton](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/captions-button): Accessible captions toggle button with availability detection and state reflection
- [CaptionsRadioGroup](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/captions-radio-group): A menu radio group for selecting caption and subtitle tracks
- [Menu](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/menu): A composable menu component for settings, option selection, and actions
### API
- [Text tracks](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-text-tracks): Subtitles, captions, and chapter track state for the player store
- [useCaptionsOptions](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-captions-options): Hook to build captions menu options from the player text track state
### Guides
- [Show timeline thumbnail previews](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/thumbnails): Preview frames along the timeline while the user scrubs, powered by a storyboard track.
- [Media sources](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/media-sources): Set what a media element plays and how its engine plays it with the structured source property
- [Accessibility](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/accessibility): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player
---
# 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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins)? 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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components).
## 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 (
);
}
```
## 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 pages
### Components
- [Controls](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/controls): Container component for composing and auto-hiding video player controls on user interaction
- [Tooltip](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/tooltip): A tooltip component for displaying contextual labels on hover and focus
### API
- [Playback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-playback): Play/pause state and actions for the player store
- [Volume](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-volume): Volume level and mute state for the player store
- [Fullscreen](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-fullscreen): Fullscreen state and actions for the player store
### Guides
- [Automatically show and hide controls](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/controls): Show controls while the user is active, hide them during playback, and toggle them by touch.
- [Accessibility](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/accessibility): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player
---
# Play live streams
Play live streams with live-edge tracking, DVR windows, and stream-type detection.
> **Note**
>
> Using a pre-built [skin](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins)? 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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components).
## Installation
The examples use HlsJsVideo, so install hls.js with the framework façade:
```bash
pnpm add @videojs/react @videojs/hlsjs-video
```
## Recommended approach
Use the live feature bundle with a streaming media element, and give users a `LiveButton`: it shows whether playback is at the live edge and seeks back to it when activated.
```tsx
import { Container, LiveButton } from '@videojs/react';
import { LiveVideoPlayer } from '@videojs/react/live-video';
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
export default function App() {
return (
{state.liveEdge ? 'LIVE' : 'Go live'} } />
);
}
```
The examples use [`HlsJsVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hlsjs-video), but any streaming media component works here, including the smaller default [`HlsVideo`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hls-video). Start with the default and switch engines only if your stream needs it.
The `liveVideoFeatures` bundle mirrors [`videoFeatures`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features) but adds the live feature and drops playback rate (not meaningful for live), quality selection, and audio-track selection. The live presets also ship skins without a time slider, duration display, or current-time display.
Both bundles are plain arrays, so extending one is a spread:
```tsx
import { createPlayer, streamTypeFeature } from '@videojs/react';
import { liveVideoFeatures } from '@videojs/react/live-video';
const { Player } = createPlayer({ features: [...liveVideoFeatures, streamTypeFeature] });
```
## How it works
Two features describe liveness:
- The [stream type feature](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-stream-type) reports `streamType`: `'live'`, `'on-demand'`, or `'unknown'`. Streaming media derives it from manifest metadata; plain media elements fall back to duration-based detection. `liveVideoFeatures` does not include it; add `streamTypeFeature` to the player’s features when you need `streamType`.
- The [live feature](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-live) reports two values:
- `liveEdgeStart` is where “live” begins on the timeline. When the playhead is at or past this time, the viewer is watching live; behind it, they’re watching earlier moments of the stream.
- `targetLiveWindow` is how far back the stream lets viewers rewind. `0` means a plain live stream that stays at the edge. `Infinity` means full DVR: rewind as far as the recording goes. `NaN` means the stream isn’t live, or the player doesn’t know yet.
The [time feature](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-time) adjusts for live playback: `duration` reports the live edge (the end of the seekable range) and keeps growing as the stream continues.
LiveButton reads this state: it renders as an active “go to live” control while playback is behind the edge, seeks to the edge on activation, and goes inactive at the edge. Until the media reports a `seekable` range — before metadata loads, or for non-live media — the button is disabled (`data-disabled`) because there is no edge to seek to. Custom live UIs should treat “behind the edge” and “actionable” as separate states.
## Availability and constraints
- `liveEdgeStart` and `targetLiveWindow` come from media that implements the live capability — the hls.js-based media elements. With plain media elements, stream type falls back to duration-based detection and `liveEdgeStart` stays `NaN`.
- Live playback drifts behind the edge when the network stalls or the tab is backgrounded. Always give users a path back to the edge.
- Seeking makes sense only for DVR streams (`targetLiveWindow` of `Infinity`). For standard-latency streams, omit the time slider.
- Playback rate control isn’t meaningful for live; `liveVideoFeatures` omits it.
## Common variations
### DVR: let users scrub back
For streams with a DVR window, give users a [TimeSlider](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/time-slider). The live preset skins don’t include one, so add it to your custom UI or [add the live skin source to your project](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source). The slider tracks the sliding window automatically because `duration` follows the live edge.
### Switch UI by stream type
Render live or on-demand controls from `streamType` when one player handles both kinds of content. Add `streamTypeFeature` to the player’s features; `liveVideoFeatures` does not include it:
The preset `LiveVideoPlayer` comes with a fixed feature set. To change it, build the player yourself with [`createPlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/create-player) — the escape hatch for custom feature sets:
```tsx
import { Container, createPlayer, LiveButton, streamTypeFeature } from '@videojs/react';
import { liveVideoFeatures } from '@videojs/react/live-video';
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
const { Player, usePlayer } = createPlayer({ features: [...liveVideoFeatures, streamTypeFeature] });
function LiveBadge() {
const streamType = usePlayer((s) => s.streamType);
if (streamType !== 'live') return null;
return {state.liveEdge ? 'LIVE' : 'Go live'} } />;
}
export default function App() {
return (
);
}
```
## Troubleshooting
### The live badge never activates
`streamType` isn’t `'live'`. Confirm the player’s features include `streamTypeFeature` (`liveVideoFeatures` does not include it, so `streamType` reads as `undefined`), the source is a live manifest, and it plays through a live-capable media element such as [HlsJsVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hlsjs-video).
### Playback keeps falling behind the edge
Network throughput can’t sustain the stream, or the tab was backgrounded. LiveButton returns users to the edge; for lower drift, review the stream’s latency configuration on the encoder side.
### The time slider behaves oddly on a live stream
Standard-latency live streams have no meaningful seek range. Show the slider only for DVR streams (`targetLiveWindow` of `Infinity`).
## Related pages
### Components
- [TimeSlider](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/time-slider): A slider component for seeking through media playback time
- [BufferingIndicator](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/buffering-indicator): Loading indicator that displays when the video player is buffering or waiting for data
### API
- [Live](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-live): Live edge state for the player store
- [Stream type](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-stream-type): Stream delivery type (live / on-demand) state for the player store
- [Time](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-time): Playback position and duration state for the player store
- [HlsJsVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hlsjs-video): HLS video element powered by hls.js for adaptive bitrate streaming
### Guides
- [Media sources](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/media-sources): Set what a media element plays and how its engine plays it with the structured source property
---
# Add a quality selector
Read available renditions, let the engine adapt automatically, and offer manual quality selection.
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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/media-sources).
> **Note**
>
> Using a pre-built [skin](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins)? 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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components).
## 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.
**App.tsx**
```tsx
import { Container, createPlayer, Menu } from '@videojs/react';
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
import { QualityRadioGroup } from '@videojs/react/ui/quality-radio-group';
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 (
}>
Quality
(
{item.label}
{item.tier ? {item.tier} : null}
{item.badge ? {item.badge} : null}
✓
)}
/>
);
}
export default function BasicUsage() {
return (
);
}
```
**App.css**
```css
.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-hint {
margin-left: 8px;
color: rgba(0, 0, 0, 0.6);
}
.menu-hint:empty {
display: none;
}
.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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-quality) 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`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-quality-options) turns this state into ready-made menu options — labels like “1080p”, an “Auto” entry, and `availability` — as the example above shows.
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 on that value.
- 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 (
lowest?.id && store.selectVideoRendition(lowest.id)}>
Data saver
);
}
export default function App() {
return (
);
}
```
## 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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hls-video) or [HlsJsVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hlsjs-video).
### 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 pages
### Components
- [QualityRadioGroup](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/quality-radio-group): A menu radio group for selecting video quality
- [Menu](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/menu): A composable menu component for settings, option selection, and actions
### API
- [Quality](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-quality): Video rendition state and actions for the player store
- [useQualityOptions](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-quality-options): Hook to build video quality menu options from the player rendition state
- [HlsVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hls-video): Lightweight HLS video element with minimal bundle size
- [HlsJsVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hlsjs-video): HLS video element powered by hls.js for adaptive bitrate streaming
- [DashVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/dash-video): DASH video element powered by dash.js for adaptive bitrate streaming
### Guides
- [Media sources](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/media-sources): Set what a media element plays and how its engine plays it with the structured source property
---
# Go fullscreen and lock orientation
Present the player fullscreen with custom controls intact, and lock screen orientation on mobile.
> **Note**
>
> Using a pre-built [skin](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins)? 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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components).
## Recommended approach
Add a [FullscreenButton](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/fullscreen-button) 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**
```tsx
import { Container, createPlayer, FullscreenButton } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';
const { Player } = createPlayer({ features: videoFeatures });
export default function BasicUsage() {
return (
{state.fullscreen ? 'Exit Fullscreen' : 'Fullscreen'} }
/>
);
}
```
**App.css**
```css
.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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-fullscreen) 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`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/create-player) — 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 (
);
}
```
To lock to something other than `landscape`, set `orientationLockType` on the player. See the [orientation lock feature](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-orientation-lock) 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';
```
`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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/keyboard-shortcuts) 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 pages
### Components
- [FullscreenButton](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/fullscreen-button): Accessible fullscreen toggle button with keyboard support and state reflection
- [Container](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/player-container): The player's visual and interaction surface for layout, fullscreen, focus, and user activity.
### API
- [Fullscreen](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-fullscreen): Fullscreen state and actions for the player store
- [Orientation lock](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-orientation-lock): Screen orientation locking while fullscreen is active
### Guides
- [Use picture-in-picture](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/picture-in-picture): Pop the video into a floating window, with availability detection and state that tracks every entry path.
---
# Use picture-in-picture
Pop the video into a floating window, with availability detection and state that tracks every entry path.
> **Note**
>
> Using a pre-built [skin](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins)? 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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components).
## Recommended approach
Add a [PiPButton](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/pip-button). It requests and exits picture-in-picture, reflects the current state, and renders nothing when picture-in-picture is unsupported.
**App.tsx**
```tsx
import { Container, createPlayer, PiPButton } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';
const { Player } = createPlayer({ features: videoFeatures });
export default function BasicUsage() {
return (
{state.pip ? 'Exit PiP' : 'Enter PiP'} }
/>
);
}
```
**App.css**
```css
.media-container {
position: relative;
}
.media-container video {
width: 100%;
}
.media-pip-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 [picture-in-picture feature](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-pip) puts three things in player state.
`pip` is `true` while the video is in a floating window. It tracks every way in and out — your button, the native controls, or a control the browser adds on its own.
`pipAvailability` answers “can I offer this?” It starts as `'unavailable'`. Once the feature attaches to a media element, it settles to `'available'` or `'unsupported'`.
`requestPictureInPicture()`, `exitPictureInPicture()`, and `togglePictureInPicture()` change the presentation. If the browser blocks a request, the returned promise rejects. In a browser with no picture-in-picture API, the actions resolve without changing anything.
Picture-in-picture and fullscreen are exclusive: requesting one exits the other first.
## Availability and constraints
- Show picture-in-picture controls only when `pipAvailability` is `'available'`. PiPButton handles this for you.
- Requests must come from a user gesture; browsers reject requests outside one.
- Firefox 153 (July 2026) added the programmatic picture-in-picture API. Earlier versions, including Firefox ESR 140, report `'unsupported'` even though they offer their own built-in picture-in-picture toggle to users.
- On iOS, picture-in-picture is supported on iPhone and iPad through the WebKit presentation mode; the player handles this path for you.
- The browser owns the floating window: its size, position, and built-in controls aren’t yours to style.
- The user can close the window or return the video at any time. React to `pip` state instead of assuming your button is the only entry and exit.
## Common variations
### Request picture-in-picture from app logic
Enter picture-in-picture when the user scrolls the player out of view or navigates within your app. This still requires a recent user gesture in most browsers, so tie it to an interaction:
```tsx
import { Container } from '@videojs/react';
import { usePlayer, Video, VideoPlayer } from '@videojs/react/video';
function WatchElsewhereButton() {
const store = usePlayer();
return (
{
store.requestPictureInPicture().catch(() => {
// Rejected: no video data yet, or blocked by the browser.
});
}}
>
Keep watching while you browse
);
}
export default function App() {
return (
);
}
```
## Troubleshooting
### The picture-in-picture button doesn’t render
`pipAvailability` is `'unsupported'` — the browser has no programmatic picture-in-picture API (Firefox before 153), or the media isn’t a video.
### The request rejects
The video has no data yet (wait for it to be ready), the call wasn’t tied to a user gesture, or the browser blocked it. Handle the rejection rather than assuming entry succeeded.
### State is wrong after the user closes the floating window
Read `pip` from player state instead of tracking entry and exit yourself; it stays in sync with every path in and out of picture-in-picture.
## Related pages
### Components
- [PiPButton](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/pip-button): Accessible picture-in-picture toggle button with keyboard support and state reflection
### API
- [Picture-in-picture](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-pip): Picture-in-picture state and actions for the player store
### Guides
- [Go fullscreen and lock orientation](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/fullscreen): Present the player fullscreen with custom controls intact, and lock screen orientation on mobile.
- [Cast to AirPlay and Chromecast](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/casting): Send playback to AirPlay and Google Cast devices, with availability detection and connection state.
---
# Show timeline thumbnail previews
Preview frames along the timeline while the user scrubs, powered by a storyboard track.
Show preview frames along the timeline while the user scrubs, like YouTube’s seek previews.
> **Tip: Using Mux?**
>
> With [MuxVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-video), the storyboard track is wired up for you — skip adding the track and go straight to the slider thumbnail. For other services, generate the storyboard on their platform and add the track yourself.
> **Note**
>
> Using a pre-built [skin](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins)? 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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components).
## Recommended approach
Add a `kind="metadata"` track labeled `thumbnails` whose cues reference storyboard images, then put a slider thumbnail inside the [TimeSlider](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/time-slider). Scrubbing shows the frame under the pointer. The slider thumbnail reads the pointer time from the slider, so you never pass `time`; it otherwise accepts the same props as the standalone [Thumbnail](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/thumbnail).
Compose `Slider.Thumbnail.Root` around `Slider.Thumbnail.Image`, and put image settings such as `crossOrigin`, `loading`, and `fetchPriority` on the image part. Inside a packaged skin, pass `renderThumbnail` to draw the image yourself; the skin still supplies `src` and sizing:
```tsx
} />
```
**App.tsx**
```tsx
import { Container, createPlayer, Slider, TimeSlider } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';
const { Player } = createPlayer({ features: videoFeatures });
export default function BasicUsage() {
return (
);
}
```
**App.css**
```css
.media-container {
position: relative;
}
.media-container video {
width: 100%;
}
.media-time-slider {
position: absolute;
right: 10px;
bottom: 6px;
left: 10px;
display: flex;
align-items: center;
height: 20px;
cursor: pointer;
}
.media-slider-track {
position: absolute;
right: 0;
left: 0;
height: 4px;
background: rgba(255, 255, 255, 0.3);
border-radius: 9999px;
transition: height 150ms ease;
}
.media-time-slider[data-interactive] .media-slider-track {
height: 6px;
}
.media-slider-fill {
position: absolute;
top: 0;
left: 0;
width: var(--media-slider-fill);
height: 100%;
background: white;
border-radius: 9999px;
}
/* Reveal the preview over the pointer while it is on the slider. */
.media-slider-thumbnail {
position: absolute;
bottom: 100%;
left: var(--media-slider-pointer);
max-width: 160px;
margin-bottom: 8px;
pointer-events: none;
border-radius: 4px;
opacity: 0;
transform: translateX(-50%);
transition: opacity 150ms ease;
}
.media-time-slider[data-pointing] .media-slider-thumbnail {
opacity: 1;
}
.media-slider-thumbnail[data-hidden] {
display: none;
}
.media-slider-thumbnail-image {
display: block;
}
```
## How it works
- Previews come from a storyboard: a `kind="metadata"` text track labeled `thumbnails` whose WebVTT cues map time ranges to image URLs (optionally with sprite coordinates). The [text track feature](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-text-tracks) exposes these as `thumbnailCues` and `thumbnailTrackSrc`.
- The slider thumbnail renders the storyboard frame for the slider’s pointer position. While the pointer is over the slider, the slider sets `data-pointing` and the `--media-slider-pointer` CSS variable; the example’s CSS uses them to reveal the preview and position it over the pointer.
- To render a storyboard frame outside the slider — a fixed preview for a chapter list, for example — use the standalone [Thumbnail](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/thumbnail) component with an explicit `time`.
Each cue’s text is an image URL. An optional `#xywh=x,y,w,h` fragment crops one frame out of a sprite sheet:
**storyboard.vtt**
```txt
WEBVTT
00:00:00.000 --> 00:00:05.000
storyboard.jpg#xywh=0,0,256,160
00:00:05.000 --> 00:00:10.000
storyboard.jpg#xywh=256,0,256,160
```
## Availability and constraints
- Thumbnails require a storyboard asset generated alongside the media; the player doesn’t extract frames from the video itself.
- Cross-origin storyboards need CORS headers, and `crossOrigin` on the media element for the track to load.
- Cues load asynchronously. The track appears before its cues are parsed, so previews fill in when the track finishes loading.
- Storyboard images download on demand; oversized sprite sheets hurt seek-preview responsiveness more than they help quality.
## Troubleshooting
### Thumbnails don’t appear while scrubbing
Confirm the storyboard track is `kind="metadata"` with `label="thumbnails"` and has the `default` attribute — the browser leaves a non-default track disabled and never loads its cues. Then confirm the VTT loads (network panel) and cross-origin assets have CORS headers with `crossOrigin` set on the media element.
### Thumbnails are blurry or slow
Regenerate the storyboard with a larger frame size, or split giant sprite sheets into smaller images.
## Related pages
### Components
- [Thumbnail](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/thumbnail): Time-based thumbnail preview component for timeline scrubbing and hover previews
- [Slider](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/slider): A composable slider component with track, fill, thumb, preview, and value parts
- [TimeSlider](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/time-slider): A slider component for seeking through media playback time
### API
- [Text tracks](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-text-tracks): Subtitles, captions, and chapter track state for the player store
### Guides
- [Add a poster and loading placeholder](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/poster): Set the image shown before playback, then add a lightweight placeholder while it loads
- [Show captions and subtitles](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/captions): Show captions and subtitles, and let users turn them on and pick a language.
---
# Cast to AirPlay and Chromecast
Send playback to AirPlay and Google Cast devices, with availability detection and connection state.
Send playback to an Apple TV over AirPlay or a Chromecast over Google Cast while the browser stays in control.
> **Note**
>
> Using a pre-built [skin](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins)? 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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components).
## Recommended approach
Use the [GoogleCast extension](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/google-cast) with a [CastButton](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/cast-button), and add an [AirPlayButton](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/airplay-button) for Safari. The prebuilt skins already include both buttons; add `GoogleCast` next to a streaming media component to enable the configurable Cast route.
**App.tsx**
```tsx
import { AirPlayButton, CastButton, Container, createPlayer } from '@videojs/react';
import { GoogleCast } from '@videojs/react/extensions/google-cast';
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
import { videoFeatures } from '@videojs/react/video';
const { Player } = createPlayer({ features: videoFeatures });
export default function BasicUsage() {
return (
(
{state.state === 'connected' ? 'Stop AirPlay' : 'Start AirPlay'}
)}
/>
(
{state.connection === 'connected' ? 'Stop casting' : 'Start casting'}
)}
/>
);
}
```
**App.css**
```css
.media-container {
position: relative;
}
.media-container video {
width: 100%;
}
.media-remote-buttons {
position: absolute;
right: 10px;
bottom: 10px;
display: flex;
gap: 8px;
}
.media-airplay-button,
.media-cast-button {
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);
}
.media-airplay-button[data-disabled],
.media-cast-button[data-disabled] {
cursor: not-allowed;
opacity: 0.5;
filter: grayscale(1);
}
```
The demo pairs the streaming media component with the `GoogleCast` extension. Without that extension, `CastButton` drives the browser’s native Remote Playback API instead, which does not provide Video.js receiver or load-request configuration.
## How it works
The [remote playback feature](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-remote-playback) gives AirPlay and Google Cast one state shape:
- `remotePlaybackAvailability` is `'available'` when a remote device can be reached, `'unavailable'` when the API exists but no device is reachable, and `'unsupported'` when the browser has no remote playback route.
- `remotePlaybackState` is `'disconnected'`, `'connecting'`, or `'connected'`.
- `toggleRemotePlayback()` opens the browser’s device picker, or disconnects an active session.
AirPlay uses WebKit’s presentation APIs. Google Cast uses a sender and receiver: the browser sends the receiver a media URL and then controls playback. Your UI reads the same Video.js state for either route.
While connected, playback actions — play, pause, seek, volume — proxy to the remote device, and player state keeps reflecting the remote session. Local playback is suspended.
The Google Cast SDK loads only when the `GoogleCast` extension is present in a Chromium browser. Players without that extension and browsers that cannot cast do not load it.
## Availability and constraints
- Remote playback is asynchronous and can fail mid-session when a device or network disappears. React to `remotePlaybackState` rather than assuming a request succeeds.
- Google Cast works only in Chromium-based browsers; elsewhere its route reports `'unsupported'`.
- AirPlay works only in Safari; availability requires an AirPlay device reachable on the network.
- The remote device fetches the source and tracks itself. Localhost, VPN-only, expired, or cross-origin URLs without the necessary CORS headers will fail on the receiver even if they play in the browser.
- Set `disableRemotePlayback` on the media element to opt out entirely.
## Common variations
### Custom Cast receiver
By default, Video.js sends the current source to Google’s Default Media Receiver. Set `receiver` when you have your own receiver application:
```tsx
```
Use `src` and `contentType` when the receiver should load a different source than the browser. `streamType` and `customData` let you describe that source and attach application-specific data. See the [GoogleCast reference](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/google-cast) for the exact option types.
### Read connection state
Use `remotePlaybackAvailability` to decide whether to offer a route and `remotePlaybackState` to show whether it is disconnected, connecting, or connected. `CastButton` and `AirPlayButton` already apply these states to their presentation; read them directly only when another part of your app needs them.
## Troubleshooting
### The cast button doesn’t render, or renders disabled
The Cast button hides when the route is unsupported. In Chromium with no Cast device reachable, it stays visible but disabled. The AirPlay button hides unless Safari reports an AirPlay device.
### Casting starts but the device shows an error
The receiver cannot fetch the media. Confirm the source URL is reachable from the device and served with CORS headers, including caption tracks.
### The UI freezes on “connecting”
The user dismissed the picker or the device disconnected. `remotePlaybackState` returns to `'disconnected'`; drive your UI from that state.
## Related pages
### Components
- [CastButton](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/cast-button): Accessible Cast toggle button with state reflection and keyboard support
- [AirPlayButton](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/airplay-button): Accessible AirPlay toggle button that opens the WebKit playback target picker and reflects session state
- [GoogleCast](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/google-cast): Options for the Google Cast extension that configures the receiver and load request
### API
- [Remote Playback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-remote-playback): Remote playback state and actions for the player store
- [HlsJsVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hlsjs-video): HLS video element powered by hls.js for adaptive bitrate streaming
### Guides
- [Media sources](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/media-sources): Set what a media element plays and how its engine plays it with the structured source property
---
# Handle playback errors
Display playback failures, report them, and choose a useful recovery action.
Display playback failures instead of leaving a dead player, report the failure when you need diagnostics, and give users a useful next step.
> **Note**
>
> Using a pre-built [skin](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins)? 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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components).
## Recommended approach
Render an [ErrorDialog](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/error-dialog) 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 (
Dismiss
);
}
```
## How it works
The [error feature](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-error) mirrors the media element’s error into player state:
- `error` holds the media’s error — `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
- For a terminal failure, load a new or refreshed source to recover. An aborted load or an adapter-specific error may have different behavior.
- Standard media error codes distinguish broad classes — aborted, network, decode, and source-not-supported — rather than root causes. A media adapter can report its own numeric code too.
- 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 new errors to your monitoring service with the source URL and `error.code`. A media error does not automatically appear in JavaScript exception monitoring.
Place a reporter inside `VideoPlayer`, alongside the skin or your custom controls:
```tsx
import { useEffect } from 'react';
import { selectError } from '@videojs/react';
import { usePlayer } from '@videojs/react/video';
function PlaybackErrorReporter({
onError,
}: {
onError: (error: { code: number; message: string }) => void;
}) {
const error = usePlayer(selectError)?.error;
useEffect(() => {
if (error) onError(error);
}, [error, onError]);
return null;
}
```
Pass a stable `onError` function that sends the error and current source URL to your monitoring service. The effect runs when the error value changes, not on every player state update.
### Diagnose a reported failure
Start with `error.code` and the affected source URL. Check the browser’s network panel for failed media requests, response status, redirects, CORS headers, and expired credentials. If requests succeed, check the file’s container and codecs against the chosen media component. For HLS or DASH, inspect the streaming engine’s diagnostics for segment and manifest failures; the player error often names only the final outcome.
## 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. If `play()` rejects with `NotAllowedError`, see [Autoplay](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/autoplay).
### A `VJS8_LEGACY_*` exception appears
These codes identify Video.js 8 APIs used with the Video.js 10 `video.js` package. Look up the code in the [error code reference](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/error-codes) for its trigger and v10 equivalent. The player `error` state covered in this guide receives media playback errors after setup.
### 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](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/media-sources).
### 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 pages
### Components
- [BufferingIndicator](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/buffering-indicator): Loading indicator that displays when the video player is buffering or waiting for data
### API
- [Error](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-error): Media error state and actions for the player store
### Guides
- [Media sources](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/media-sources): Set what a media element plays and how its engine plays it with the structured source property
- [Autoplay](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/autoplay): Start playback automatically and handle browser autoplay restrictions.
---
# Remember user preferences
Persist volume, caption, and quality preferences across sessions by subscribing to player state.
The player doesn’t persist preferences itself today. Player state gives you everything needed to wire persistence to the storage you choose — local storage, your backend, or per-profile settings.
## Recommended approach
Subscribe to the state you want to remember, write it to storage when it changes, and restore it once the store attaches to the media.
```tsx
import { useEffect, useRef, useState } from 'react';
import { Container } from '@videojs/react';
import { usePlayer, Video, VideoPlayer } from '@videojs/react/video';
const STORAGE_KEY = 'player:volume';
// Local storage can be unavailable (private modes), so guard reads and writes.
function readSaved() {
try {
return JSON.parse(localStorage.getItem(STORAGE_KEY) ?? 'null');
} catch {
return null;
}
}
function save(prefs: { volume: number; muted: boolean }) {
try {
localStorage.setItem(STORAGE_KEY, JSON.stringify(prefs));
} catch {
// Storage unavailable; skip persistence.
}
}
function VolumePersistence() {
const store = usePlayer();
const { volume, muted } = usePlayer((s) => ({ volume: s.volume, muted: s.muted }));
// Read the saved value once, before the save effect below can write.
const [saved] = useState(readSaved);
const restored = useRef(false);
// Save on change, once the restore has run.
useEffect(() => {
if (!restored.current) return;
save({ volume, muted });
}, [volume, muted]);
// Restore once the store attaches to the media; actions throw before that.
useEffect(() => {
const restore = () => {
if (!store.target) return false;
if (saved) {
store.setVolume(saved.volume);
// setVolume above zero unmutes, so mute again if that's the saved preference.
// At volume zero the player already counts as muted, and toggling would unmute.
if (saved.muted && saved.volume > 0) store.toggleMuted();
}
restored.current = true;
return true;
};
if (restore()) return;
const unsubscribe = store.subscribe(() => {
if (restore()) unsubscribe();
});
return unsubscribe;
}, [store, saved]);
return null;
}
export default function App() {
return (
);
}
```
## How it works
- Player state is the single source of truth: it already reflects every change, whatever caused it — your UI, keyboard shortcuts, native controls, or scripts.
- `store.subscribe(callback)` fires on any state change. Notifications are batched per microtask, so rapid changes (a volume drag) produce one callback per tick, which keeps storage writes cheap. There is no per-key subscription on the store: read the state and diff the slice you care about.
- `usePlayer(selector)` re-renders only when the selected value changes; pairing it with an effect is the idiomatic save path.
- Feature selectors exported by `@videojs/react` (`selectVolume`, `selectTextTrack`, `selectQuality`, and the rest) read a feature’s slice from any store, returning `undefined` when the feature isn’t present.
- Restore through the feature actions (`setVolume`, `toggleMuted`, `selectSubtitlesTrack`, `selectVideoRendition`) rather than poking the media element, so state and UI stay consistent.
- Actions need an attached media target: calling one before the store attaches throws. Check `store.target` and defer the restore until it is set, as the examples do.
## Availability and constraints
- Nothing persists by default: volume resets to the media element’s value, captions to the track markup, quality to automatic, on every load.
- `setVolume` clamps to 0–1 and unmutes when setting a value above zero; restore volume first, then toggle `muted` back on when the saved preference is muted, as the examples do. Skip the toggle when the saved volume is zero: the player treats volume zero as muted, so toggling would unmute and raise the volume. Don’t compare against store state right after calling an action: notifications batch per microtask, so that state is still stale.
- Restore track and quality selections after the media exposes them: track and rendition lists arrive when the media loads, not at player creation. Subscribe and apply when the saved entry appears in the list.
- Programmatic volume control is unavailable on some platforms (after attach, iOS Safari reports `volumeAvailability: 'unsupported'`); volume persistence quietly does nothing there.
- Local storage is per-origin and can be unavailable (private modes, embedded contexts); guard reads and writes accordingly.
## Common variations
### Persist caption preference
Save the showing track’s `language` (not its generated id, which can change between sources), or `'off'` when the user turns captions off. Restoring is two phases: while the media loads, assert the saved preference whenever the track modes drift from it, because browsers can auto-enable a track of their own during loading. Once the media can play (`canPlay`), treat every change as the user’s choice and save it. A restore that re-runs forever would keep overriding the user; one that runs only once can get overridden by the browser.
```tsx
function CaptionsPersistence() {
const store = usePlayer();
const { tracks, canPlay } = usePlayer((s) => ({ tracks: s.textTrackList, canPlay: s.canPlay }));
const [saved] = useState(() => localStorage.getItem('player:captions'));
const restored = useRef(false);
useEffect(() => {
const subtitles = tracks.filter((t) => t.kind === 'captions' || t.kind === 'subtitles');
if (!subtitles.length) return;
// Restore phase: assert the saved preference until the media can play.
if (!restored.current) {
const desired = saved === 'off' ? undefined : subtitles.find((t) => t.language === saved);
if (saved && (desired || saved === 'off')) {
const applied = subtitles.every((t) => (t.mode === 'showing') === (t.id === desired?.id));
if (!applied) {
store.selectSubtitlesTrack(desired?.id ?? 'off');
return;
}
}
if (!canPlay) return;
restored.current = true;
}
// Save phase: the showing track's language, or 'off'.
const showing = subtitles.find((t) => t.mode === 'showing');
localStorage.setItem('player:captions', showing ? showing.language : 'off');
}, [store, tracks, canPlay, saved]);
return null;
}
```
### Persist to your backend
Swap `localStorage` for an API call; the subscription pattern is identical. Debounce writes beyond the built-in microtask batching if your storage is remote.
## Troubleshooting
### The saved volume doesn’t apply
Restore runs before the store attaches, or the platform doesn’t allow programmatic volume (check `volumeAvailability`). Apply after `store.target` is set, as in the examples.
### The saved caption track doesn’t select
The track list wasn’t loaded yet when you restored, or you saved a generated track id instead of a stable property like `language`. React to `textTrackList` changes and match on language.
### Storage writes fire constantly while dragging the volume slider
Notifications batch per microtask, but a drag still produces many ticks. Debounce the write if the churn matters for your storage target.
## Related pages
### Components
- [VolumeSlider](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/volume-slider): A slider component for controlling media playback volume
- [CaptionsRadioGroup](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/captions-radio-group): A menu radio group for selecting caption and subtitle tracks
- [QualityRadioGroup](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/quality-radio-group): A menu radio group for selecting video quality
### API
- [usePlayer](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-player): Hook to access the player store from within a Player
- [useStore](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-store): Hook to access store state and actions with optional selector-based subscriptions
- [Volume](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-volume): Volume level and mute state for the player store
- [Text tracks](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-text-tracks): Subtitles, captions, and chapter track state for the player store
### Guides
- [Show captions and subtitles](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/captions): Show captions and subtitles, and let users turn them on and pick a language.
- [Add a quality selector](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/quality): Read available renditions, let the engine adapt automatically, and offer manual quality selection.
---
# Add a background video
Add an accessible background video from an MP4, WebM, HLS, or Mux source
Add a decorative video behind your page content. Start with an MP4 or WebM file, which browsers can play directly. If your video is delivered as HLS, use the HLS or Mux option below.
## Recommended approach
Use [BackgroundVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/background-video) with an MP4 or WebM URL. Put the video and poster inside a wrapper with `aria-hidden="true"` because both are decorative. Keep the heading, links, and other page content outside that wrapper.
**App.tsx**
```tsx
import { BackgroundVideo } from '@videojs/react/media/background-video';
export default function BasicUsage() {
return (
);
}
```
**App.css**
```css
.add-background-video-react-demo {
position: relative;
display: grid;
min-height: 18rem;
overflow: hidden;
color: white;
background: black;
border-radius: 0.5rem;
isolation: isolate;
}
.add-background-video-react-demo__visual,
.add-background-video-react-demo__poster,
.add-background-video-react-demo__media {
position: absolute;
inset: 0;
width: 100%;
height: 100%;
}
.add-background-video-react-demo__visual {
pointer-events: none;
}
.add-background-video-react-demo__visual::after {
position: absolute;
inset: 0;
content: "";
background: linear-gradient(90deg, rgb(0 0 0 / 85%), rgb(0 0 0 / 55%));
}
.add-background-video-react-demo__poster,
.add-background-video-react-demo__media {
display: block;
object-fit: cover;
}
.add-background-video-react-demo__media {
--media-object-fit: cover;
--media-object-position: center;
}
.add-background-video-react-demo__content {
position: relative;
z-index: 1;
display: grid;
gap: 1rem;
place-content: end start;
max-width: 28rem;
padding: 2rem;
}
.add-background-video-react-demo__content h3 {
margin: 0;
font-size: 1.75rem;
line-height: 1.1;
}
.add-background-video-react-demo__content a {
width: fit-content;
padding: 0.625rem 1rem;
color: black;
text-decoration: none;
background: white;
border-radius: 0.25rem;
}
.add-background-video-react-demo__content a:focus-visible {
outline: 0.2rem solid white;
outline-offset: 0.2rem;
}
@media (prefers-reduced-motion: reduce) {
.add-background-video-react-demo__media {
display: none;
}
}
```
## How it works
BackgroundVideo renders the browser’s `` element and starts it muted, looped, autoplaying, and inline. The example puts that video and an empty-alt poster in the `.hero-visual` wrapper. The wrapper is hidden from assistive technology and ignores pointer input, so it does not act like a media player.
The page defines the hero’s size. The video fills that space with `--media-object-fit: cover`, while the poster remains visible until the video paints a frame. The reduced-motion rule hides the video and leaves the poster in place.
Set the size, position, and transforms on the `.hero-visual` wrapper so the poster and video stay together.
## Availability and constraints
- Use a source the browser can play directly, such as MP4 or WebM.
- Safari can play HLS URLs directly. Other browsers cannot do so reliably, so use an HLS variation below when the same `.m3u8` URL must work across browsers.
- BackgroundVideo does not create a poster or report analytics. Keep the poster in your page and add analytics only when you need them.
- Video.js does not apply a reduced-motion policy for you. The example stops the decoration with `prefers-reduced-motion`.
- If the video communicates information, remove `aria-hidden`, give it an accessible name and controls, and use a regular video player.
## Common variations
Choose a variation based on the source you already have:
| Need | Use |
| --- | --- |
| Cross-browser HLS with a small background-only player | [HlsBackgroundVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hls-background-video) |
| The same background-only player for a Mux HLS URL | [MuxBackgroundVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-background-video) |
### Play an HLS video
HlsBackgroundVideo plays an HLS video without adding controls, audio, or captions. Pass a complete HLS URL through `src`:
```bash
pnpm add @videojs/react @videojs/spf
```
```tsx
import { HlsBackgroundVideo } from '@videojs/react/media/hls-background-video';
console.error('The background stream could not play')}
/>
```
Your HLS stream must be unencrypted and use fragmented MP4 video segments, also called fMP4 or CMAF. The component chooses one video size when playback starts and does not switch sizes later. It cannot play older MPEG-TS segments.
### Play a Mux HLS URL
MuxBackgroundVideo is a Mux-named alias for HlsBackgroundVideo. Pass a complete Mux HLS URL, not a bare playback ID or `source` object:
It uses the same `@videojs/spf` installation shown for HlsBackgroundVideo above.
```tsx
import { MuxBackgroundVideo } from '@videojs/react/media/mux-background-video';
```
This component does not create a Mux poster, preview thumbnails, or analytics session. Keep the poster in your page and add analytics separately when you need them.
## Troubleshooting
### An HLS URL works in Safari but not another browser
BackgroundVideo hands its `src` to the browser’s `` element. Use HlsBackgroundVideo for a supported fMP4 HLS source, or MuxBackgroundVideo for a Mux HLS URL.
### The video does not fill or follow transforms
Set the size, transforms, and measurements on the wrapper that contains the video and poster. Size the background-video component to fill that wrapper.
### No poster or Mux analytics appear
The background-video components do not provide them. Render an empty-alt poster in the same wrapper as the video, and add analytics separately.
## Related pages
### Components
- [BackgroundVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/background-video): Decorative background video element with automatic muting and looping
- [HlsBackgroundVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hls-background-video): HLS background video without controls, audio, captions, or adaptive quality
- [MuxBackgroundVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-background-video): Mux-specific name for the HLS background video component
### Guides
- [Add a poster and loading placeholder](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/poster): Set the image shown before playback, then add a lightweight placeholder while it loads
---
# Internationalize the player
Translate player labels and announcements: shipped locale packs, custom translations, runtime switching, and server rendering.
Translate every player label, tooltip, and screen-reader announcement. The player ships translations for more than 50 locales and loads them on demand.
## Recommended approach
Wrap the player in the i18n provider. It resolves the locale from your page’s `lang` attribute (or an explicit override), lazy-loads the matching locale pack, and every component label follows.
```tsx
import { Container } from '@videojs/react';
import { I18nProvider } from '@videojs/react/i18n';
import { Video, VideoPlayer } from '@videojs/react/video';
export default function App() {
return (
);
}
```
Omit `locale` to follow the nearest ancestor `lang` attribute (usually ``).
Pick a language and every label follows — no remount:
**App.tsx**
```tsx
import { createPlayer } from '@videojs/react';
import { I18nProvider, LOCALES } from '@videojs/react/i18n';
import { Video, VideoSkin, videoFeatures } from '@videojs/react/video';
import { useState } from 'react';
import '@videojs/react/video/skin.css';
import './Language.css';
const { Player } = createPlayer({ features: videoFeatures });
const locales = ['en', ...LOCALES] as const;
type Locale = (typeof locales)[number];
const languageNames = new Intl.DisplayNames(['en'], { type: 'language' });
export default function Language() {
const [locale, setLocale] = useState('en');
return (
Language
setLocale(event.currentTarget.value as Locale)}>
{locales.map((value) => (
{languageNames.of(value) ?? value}
))}
);
}
```
**App.css**
```css
.react-i18n-language {
display: grid;
gap: 16px;
padding: 16px;
}
.react-i18n-language label {
display: flex;
gap: 8px;
align-items: center;
}
.react-i18n-language select {
padding: 4px 8px;
}
.react-i18n-language__player {
width: 100%;
aspect-ratio: 16 / 9;
}
```
## How it works
- Component labels are text descriptors — a translation key plus its English default — so everything renders in English with no setup and switches language when a translator is present. Keys are stable: `buttons.play` stays `buttons.play` even if the English wording changes.
- The provider resolves the locale: explicit `locale` first, then the nearest ancestor `lang` attribute, then `'en'`. It re-resolves when the page’s `lang` changes.
- The provider lazy-loads the pack for the resolved locale automatically and keeps it in a layer above the shared registry ([`registerI18n`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/register-i18n)). Translations merge along a fallback chain that follows the [BCP 47](https://www.rfc-editor.org/rfc/rfc5646) parent tags — `es-MX` checks `es`, then `en` — so a regional pack only has to carry the text that differs from its parent.
- Each piece of text resolves from the first source that has it:
1. Overrides supplied to the current player (the `translations` prop)
2. Registered custom translations
3. A built-in locale pack
4. The component’s English fallback
- `registerI18n(locale, translations)` **merges**: each call adds or replaces keys for that locale without wiping prior registrations, and later registrations win for the same key. Register a locale before the provider resolves it — a pack the provider already lazy-loaded sits above the registry and hides registry entries for that locale. Overriding a handful of strings is the same call as registering a full locale.
- When no shipped pack matches the locale, the provider can fall back to the browser’s on-device Translation API to machine-translate the English catalogue, with placeholders preserved.
Translate your own UI with the same machinery:
```tsx
import { useTranslator } from '@videojs/react/i18n';
function StartButton() {
const t = useTranslator();
return {t('buttons.play', { default: 'Play' })} ;
}
```
The `default` is the English text — English ships inside component descriptors, not as a pack, so a bare `t(key)` renders the key itself under `en`. The key selects the translation once a pack is active.
## Availability and constraints
- English is built in; every other locale is a lazy-loaded pack. Server rendering needs an explicit `locale` since there’s no DOM to resolve from.
- Locale tags are [BCP 47](https://www.rfc-editor.org/rfc/rfc5646) (`es`, `pt-BR`).
- Translation keys are namespaced strings (`buttons.play`, `errors.network`, `menu.quality`); the full list lives at [Translation phrases](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/translation-phrases) and is typed, so typos in `registerI18n` objects fail in TypeScript. The translator itself accepts any string; a mistyped `t()` key falls back to its `default`.
- Some strings interpolate parameters; custom translations must keep the placeholders:
```ts
// ✅
registerI18n('es', { seek: { forward: 'Adelantar {seconds} segundos' } });
// ❌ The interpolated value is lost
registerI18n('es', { seek: { forward: 'Adelantar' } });
```
- The Browser Translation API fallback needs Chrome with `globalThis.Translator` and downloads an on-device model on first use. It’s best-effort; ship a real pack for languages you support officially.
## Common variations
### Override specific strings
Pass `translations` on [`I18nProvider`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/i18n-provider) to scope overrides to one subtree. This layer sits above the registry and lazy packs:
```tsx
{/* player */}
```
Nested providers inherit the parent locale when you only pass `translations`. For global overrides, call `registerI18n` instead — it merges, so only the keys you pass change.
### Register your own locale
Registered packs are partial: missing keys fall back through the locale chain to a shipped pack or English.
```ts
import { registerI18n, type Translations } from '@videojs/react/i18n';
const es = {
buttons: {
play: 'Reproducir',
pause: 'Pausa',
mute: 'Silenciar',
unmute: 'Activar sonido',
},
} satisfies Partial;
registerI18n('es', es);
```
### Register a pack with the bundle
Skip lazy loading by registering a shipped locale at startup with a side-effect import. First paint is synchronous in that language:
```ts
import '@videojs/react/i18n/locales/ja/register';
```
### Switch locale at runtime
The simplest switch updates the document language and lets providers pick it up — no remount required:
```ts
document.documentElement.lang = 'fr';
```
Ambient switching only applies when `I18nProvider` has no explicit `locale`. To drive it from state:
```tsx
const [locale, setLocale] = useState<'en' | 'es' | 'fr'>('en');
{/* player */}
```
Changing `locale` lazy-loads the pack, which can briefly show English. Preload the locales your picker offers:
```tsx
import '@videojs/react/i18n/locales/es/register';
import '@videojs/react/i18n/locales/fr/register';
```
Or prefetch and register right before switching when you can’t register everything up front:
```tsx
import { registerI18n } from '@videojs/react/i18n';
const loaders = {
es: () => import('@videojs/react/i18n/locales/es'),
fr: () => import('@videojs/react/i18n/locales/fr'),
};
async function switchTo(next: keyof typeof loaders) {
const { default: translations } = await loaders[next]();
registerI18n(next, translations);
setLocale(next);
}
```
### Set text direction
`lang` identifies the content language. `dir` controls text and layout direction. Browsers do not infer one from the other, so set both when the locale applies to the whole document:
```ts
document.documentElement.lang = 'ar';
document.documentElement.dir = 'rtl';
```
Set `dir` back to `ltr` when you switch to a left-to-right language. This prevents the previous direction from remaining active.
When `I18nProvider` has an explicit `locale`, the player applies its resolved `lang` and `dir` to the container. A `lang` or `dir` passed to that container overrides the rendered DOM boundary only; translations still come from `I18nProvider locale`.
Providers without an explicit locale inherit ambient document language and direction. In that case, set `lang` and `dir` on `` or another ancestor:
```html
```
RTL preserves playback control ordering and time-semantic media icons while mirroring menu motion and navigation chevrons. Horizontal time and volume sliders retain a physical left-to-right value scale: Left Arrow decreases the value, Right Arrow increases it, and the minimum remains on the left.
### Replace a component’s visible text
Translation overrides change built-in labels everywhere they appear. To replace only one component’s visible content, set its children — and use the translation machinery when that content should still follow the active locale:
```tsx
import { LiveButton } from '@videojs/react';
On air
```
Authored children are literal; use `useTranslator` when custom children also need localization. For state-dependent text, render one element per state and show or hide them with the component’s `data-*` state attributes (the same pattern used for icons).
The component still derives its accessible name from media state unless you also set its label API. Keep custom visible text consistent with that name.
### Server rendering
Render the document language on the server (``) and make translations available before first paint so labels match on server and client:
Import the pack on the server and pass it to the provider — `translations` on first render skips the async lazy layer entirely:
```tsx
const loaders = {
es: () => import('@videojs/react/i18n/locales/es'),
fr: () => import('@videojs/react/i18n/locales/fr'),
};
export async function Player({ locale }: { locale: string }) {
const load = loaders[locale as keyof typeof loaders];
if (!load) throw new Error(`Unsupported locale: ${locale}`);
const { default: translations } = await load();
return (
{/* player */}
);
}
```
Pass `locale` explicitly on the server — there’s no DOM to resolve `lang` from, and an explicit value avoids hydration mismatches. With app routers, pass the tag your framework negotiates (for next-intl, `await getLocale()`); Video.js doesn’t replace framework i18n, it consumes the tag you give it.
## Troubleshooting
### Labels stay in English
No provider is mounted, or the locale never resolved: check the `locale`/`lang` value and that it matches a shipped pack (regional tags fall back — `pt-BR` works; a bare unknown tag falls through to English).
### Some strings are translated, others aren’t
A partial override or partial pack: missing keys fall back through the locale chain to English. Fill in the missing keys with `registerI18n`.
### Translations flash in after load or after switching
The lazy pack loads after first paint (or after the switch). Register the pack with the bundle (the `/register` side-effect import), or prefetch and register before changing the locale.
### Server-rendered labels don’t match the client
The provider resolved different locales on server and client. Pass an explicit `locale` and first-render `translations` instead of relying on ambient `lang`.
## Related pages
### Components
- [I18nProvider](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/i18n-provider): React provider that resolves locale and supplies a typed translator to descendants
### API
- [registerI18n](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/register-i18n): Register or merge translation strings for a BCP 47 locale tag in the global i18n registry
- [Translation phrases](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/translation-phrases): Semantic i18n keys, their English defaults, and the player UI that uses them
- [useTranslator](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-translator): React hook that returns the typed translator for the nearest I18nProvider
- [useLocale](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-locale): React hook that returns the active BCP 47 locale from the nearest I18nProvider
- [getI18nTranslations](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/get-i18n-translations): Read the merged translation map for a locale using BCP 47 parent-chain fallback
### Guides
- [Show captions and subtitles](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/captions): Show captions and subtitles, and let users turn them on and pick a language.
- [Accessibility](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/accessibility): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player
---
# Monitor playback with Mux Data
Measure startup time, rebuffering, failures, and watch time by adding the Mux Data extension to a player
[Mux Data](https://www.mux.com/data) measures playback quality: startup time, rebuffering, playback failures, and watch time. Add the Mux Data [extension](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/architecture) to a player and it monitors whichever media that player is playing:
Install the extension alongside the framework façade. The MuxVideo example also installs the Mux playback adapter:
```bash
pnpm add @videojs/react @videojs/mux-video @videojs/mux-data
```
**App.tsx**
```tsx
import { Container, createPlayer } from '@videojs/react';
import { MuxData } from '@videojs/react/extensions/mux-data';
import { MuxVideo } from '@videojs/react/media/mux-video';
import { videoFeatures } from '@videojs/react/video';
const { Player } = createPlayer({ features: videoFeatures });
export default function App() {
return (
);
}
```
That’s the whole setup for Mux-hosted playback — no environment key required. The extension renders nothing; place it inside the player, as a sibling of the media element.
> **Note**
>
> Mux Data is opt-in. No media element monitors playback on its own, Mux ones included, so nothing is measured and no beacons are sent until you add the extension.
## Set the environment key
Mux Data needs to know which environment a view belongs to. For Mux-hosted playback it works that out on its own: the component reports the Mux playback ID as the view’s `video_id`, and Mux attributes the view to the environment that owns that playback ID.
Set `envKey` when you monitor a source Mux doesn’t host, like a self-hosted HLS or DASH stream. Find the key in the [Mux dashboard](https://dashboard.mux.com/settings/data):
```tsx
```
An explicit key always wins, so set one to send Mux-hosted views to a specific environment.
## How it works
The extension attaches to the media the player is using, not to a specific element type, so it monitors [MuxVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-video), [HlsJsVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hlsjs-video), [DashVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/dash-video), and the rest alike.
How much it reports depends on the engine playing the stream. Every media gets the playback metrics the media element itself can tell us. On top of that, the component recognizes [hls.js](https://github.com/video-dev/hls.js/) and [dash.js](https://github.com/Dash-Industry-Forum/dash.js) engines and hands them to the Mux Data SDK, which adds stream-level detail: rendition switches, segment request timing and throughput, and engine errors. Media with no JavaScript engine, like native HLS or a plain ``, report the element-level metrics alone.
The `video_id` it reports is the Mux playback ID for streams served from `stream.mux.com`, and the source URL otherwise. Each view also gets a generated `view_session_id`. Override either through `metadata`.
## Describe the view
Pass Mux Data [metadata](https://www.mux.com/docs/guides/make-your-data-actionable-with-metadata) to label views with your own titles, viewer IDs, and custom dimensions. It’s an object, so it’s a property rather than an attribute:
```tsx
```
## Configuration
The [MuxData reference](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-data) lists every option: the metadata and software fields above, plus the beacon domain, cookie, debug, and SDK settings. Most options update the current view in place; changing `MuxDataSdk`, `beaconCollectionDomain`, `debug`, or `disableCookies` restarts monitoring, ending the current view and starting a new one.
## Related pages
### Components
- [MuxData](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-data): Options for the Mux Data extension that monitors playback quality
- [MuxVideo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-video): Video element for Mux-hosted HLS streams
- [MuxAudio](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-audio): Audio element for Mux-hosted HLS streams
### Guides
- [Cast to AirPlay and Chromecast](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/casting): Send playback to AirPlay and Google Cast devices, with availability detection and connection state.
---
# Migrate from Video.js 8
Move a Video.js 8 integration to v10, mapping the options object, techs, plugins, and player API onto composed components
Video.js 8 gives you one function, `videojs()`, and one large options object. It enhances a `` element and returns a player with a control bar, plugin system, and component tree.
Video.js v10 is a rebuild, not a drop-in version bump. There is no `videojs()` call, options object, or plugin registry. You compose a player from a few named pieces instead.
> **Caution**
>
> This isn’t a version bump you can do with a find-and-replace. Plan it as a rewrite of your player setup, and read this guide before you estimate it.
Video.js 8 lives on at its [repo](https://github.com/videojs/video.js) and [docs](https://legacy.videojs.org).
## Three pieces instead of one
In v8 the player was everything: playback, UI, and the skin on top of it. Options configured all three, which is why the options object grew so large.
v10 splits those jobs up. Learning the three names first makes the rest of this guide much shorter.
**The player** is the outer element. It holds state and hands that state to everything inside it, and it draws nothing. This is the closest thing to a v8 `player` instance, but it owns state rather than DOM. Which state it holds depends on the [features](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features) it’s built from.
**The media** is the thing that plays the video. This is where v8’s *tech* went. A plain `` plays progressive files, and there’s a [media component](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/media-sources) for HLS, DASH, YouTube, Vimeo, and Mux. Swapping one for another is a tag change, and the rest of your player keeps working.
**The skin** is the UI: the controls, the poster, the captions, the settings menu, the keyboard shortcuts. It’s the v8 control bar and skin combined, except [skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins) are plain trees of components you can read and edit rather than a class hierarchy you subclass.
So a v8 embed becomes a player wrapped around a skin wrapped around a media:
```jsx
```
Most of this guide is about which of those three a given v8 option now belongs to.
## Your first player
v8 shipped no React package, so you were managing a ref, calling `videojs()` in an effect, and disposing on unmount. Something like this:
```tsx
import { useEffect, useRef } from 'react';
import videojs from 'video.js';
import 'video.js/dist/video-js.css';
export function MyPlayer() {
const containerRef = useRef(null);
const playerRef = useRef | null>(null);
useEffect(() => {
const el = document.createElement('video-js');
containerRef.current?.appendChild(el);
playerRef.current = videojs(el, {
controls: true,
preload: 'auto',
poster: '/poster.jpg',
sources: [{ src: '/video.mp4', type: 'video/mp4' }],
});
return () => playerRef.current?.dispose();
}, []);
return
;
}
```
`@videojs/react` replaces all of that with real components.
```bash
npm install @videojs/react
```
One new idea here. Instead of one `videojs()` that does everything, you pick a [preset](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets) that matches what you’re building. A preset is a player, a skin, and a media element that already fit together. `@videojs/react/video` is the general-purpose one, and it’s what you want unless you know you need something unusual.
```tsx
'use client';
import '@videojs/react/video/skin.css';
import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
export function MyPlayer() {
return (
);
}
```
`VideoPlayer` is the piece that owns the state. To read that state, the preset ships a matching [`usePlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-player) hook. There’s no ref to manage and no disposal to remember.
Three differences worth understanding, because each one is a pattern you’ll see again:
- **No `videojs()` call and no effect.** `VideoPlayer` owns the lifecycle.
- **No `controls` prop.** The skin *is* the controls. Rendering a skin is how you ask for them, which is also how you opt out.
- **The poster is player metadata, not a media attribute.** Pass it to `VideoPlayer`, and the skin controls how it appears.
The `'use client'` directive is there because the player owns browser state. There’s also a minimal skin, closer to v8’s control bar, if the default’s frosted look is too much of a change.
## Where your options went
The v8 options object is gone, and its contents scattered in four directions. This is the biggest conceptual step, so it’s worth understanding the four buckets before you go looking for a specific option.
1. **Media attributes.** Anything the browser itself understands stays exactly where it was, on your media element.
2. **Player metadata.** The title and poster belong to player state, which lets the skin or your custom UI render them.
3. **Your CSS.** Sizing, aspect ratio, and responsive behavior are layout, and layout is yours.
4. **Composition.** Which controls exist, which shortcuts fire, which language you’re in. You express these by choosing components rather than by setting flags.
### Media attributes
Port these across untouched. They’re native attributes and always were.
| Video.js 8 | Video.js v10 |
| --- | --- |
| `autoplay`, `muted`, `loop`, `preload`, `playsinline`, `crossorigin` | the same attributes on your media |
| `sources: [{ src, type }]` | `src`, or `` children for progressive fallback |
| `disablePictureInPicture` | `disablepictureinpicture` |
### Player metadata
| Video.js 8 | Video.js v10 |
| --- | --- |
| `poster` | `poster` on `VideoPlayer` |
| `posterImage: false` | leave the player’s poster unset |
| the title in `TitleBar` | `title` on `VideoPlayer`, rendered with the Title component |
The poster belongs to player state rather than the media, which lets the skin control how it appears:
```jsx
```
The packaged video and live-video skins already include the [Title](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/title) component, so setting `title` on the player displays it. Audio skins do not include a title. Add `Title` where you want it in a custom layout or skin source you added to your project. For poster rendering options — including placeholders and custom image elements — see [Add a poster and loading placeholder](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/poster) and the [Poster](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/poster) reference.
### Your CSS
v8 had a small sizing language of its own. v10 doesn’t, because CSS already has one.
| Video.js 8 | Video.js v10 |
| --- | --- |
| `fluid: true` | `width: 100%` on the skin |
| `responsive: true` | the skins already adapt their layout to their own width |
| `aspectRatio: '16:9'` | `aspect-ratio: 16 / 9` |
| `width`, `height` | `width`, `height` |
| `fill: true` | `width: 100%; height: 100%` |
| `breakpoints` | the skins use container queries internally; use your own for your layout |
### Composition
These are the ones that need a decision rather than a rename, so each has a section below.
| Video.js 8 | Where it lives now |
| --- | --- |
| `techOrder`, `html5.vhs.*` | [Techs become media components](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-video-js-8#techs-become-media-components) |
| `children`, `controlBar: { … }` | [Customize your player](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-video-js-8#customize-your-player) |
| `userActions.hotkeys`, `userActions.click`, `userActions.doubleClick` | [Customize your player](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-video-js-8#customize-your-player) |
| `plugins`, `videojs.registerPlugin` | [Plugins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-video-js-8#plugins) |
| `languages`, `language`, `videojs.addLanguage` | [Languages](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-video-js-8#languages) |
| `liveui`, `liveTracker` | [Live and audio-only](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-video-js-8#live-and-audio-only) |
| `audioOnlyMode`, `audioPosterMode` | [Live and audio-only](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-video-js-8#live-and-audio-only) |
| `playbackRates` | not configurable yet ([#1404](https://github.com/videojs/v10/issues/1404)) |
| `textTrackSettings` | no equivalent; see [Known gaps](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-video-js-8#known-gaps) |
| `spatialNavigation` | no equivalent; see [Known gaps](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-video-js-8#known-gaps) |
| `inactivityTimeout` | delay not configurable yet ([#1728](https://github.com/videojs/v10/issues/1728)); `inactivityTimeout: 0` maps to `visibility="always"` on the controls component |
| `errorDisplay`, `notSupportedMessage` | the skins include an error dialog |
| `ModalDialog` | compose a [dialog](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/dialog); your application controls media playback when it opens and closes |
## Techs become media components
v8’s tech system was one of its harder ideas: an abstraction layer with a registry, a resolution order, and source handlers on top. Getting HLS meant getting VHS, which meant reasoning about `overrideNative` and hoping the right thing won.
v10 replaces the whole mechanism with a choice you make in markup. You pick the [media component](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/media-sources) that plays your format, and that’s the tech decision.
| What you’re playing | Video.js 8 | Video.js v10 |
| --- | --- | --- |
| MP4, WebM | `techOrder: ['html5']` | a plain `` |
| HLS | VHS | [HLS video](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hls-video) |
| HLS, needing hls.js directly | `videojs.Vhs` | [hls.js video](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/hlsjs-video) |
| HLS, native only | `html5.vhs.overrideNative: false` | [native HLS video](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/native-hls-video) |
| DASH | VHS | [DASH video](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/dash-video) |
| YouTube, Vimeo | a tech plugin | the YouTube and Vimeo components |
| Mux | a tech plugin | [Mux Video](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-video) |
Each needs its own import.
Package-manager installations also need the matching media package. The default HLS component shown below uses `@videojs/spf`; the hls.js component uses `@videojs/hlsjs-video`; Mux video and audio use `@videojs/mux-video` and `@videojs/mux-audio`; DASH uses `@videojs/dash-video`; Vimeo uses `@videojs/vimeo-video`; and Shaka and Wistia use `@videojs/shaka-video` and `@videojs/wistia-video`.
For HLS, import the component and swap it for ``:
```bash
npm install @videojs/react @videojs/spf
```
```tsx
import { HlsVideo } from '@videojs/react/media/hls-video';
```
Start with the default HLS component, and move to hls.js if you hit something it doesn’t handle. The default runs on SPF, Video.js’s own playback engine, and it’s the reason v10 can be as small as it is. The hls.js one is a much larger download but more compatible, supporting TS-packaged media and DRM.
Your VHS tuning options don’t have direct equivalents. Rendition capping, bandwidth hints, and the rest are engine-specific, so they belong to whichever engine you chose rather than to a shared options object.
## Customize your player
In v8, customizing meant three different techniques depending on what you wanted: options for some things, `addChild` and component subclassing for others, and CSS overrides on `.vjs-*` selectors for the look. v10 has one path with three levels of commitment. Try them in order.
### Level 1: pick a skin
The default skin is a modern, frosted look. The minimal skin is closer to v8’s control bar. Both bring controls, tooltips, captions, keyboard shortcuts, touch gestures, and a settings menu that appears when there’s something to put in it. See [Skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins).
Both also include AirPlay and Cast buttons, which v8 had no answer for. Follow [Cast to AirPlay and Chromecast](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/casting) to add the Google Cast extension. Remote playback is a feature you compose in rather than a plugin you install.
### Level 2: restyle it
v8 customization meant writing selectors against internal class names and hoping they survived the next release. v10 skins expose custom properties instead, which are part of the public surface:
```css
/* Video.js 8 */
.video-js .vjs-play-progress {
background-color: rebeccapurple;
}
/* Video.js v10 */
video-player {
--media-accent-color: rebeccapurple;
}
```
`--media-accent-color` reaches the sliders, the active buttons, and the accent surfaces at once. Video.js derives a readable text color to sit on top of it; override that with `--media-accent-text-color` if you’d rather choose. `--media-border-radius` rounds the player, and `--media-scale-unit` scales the whole control bar, which is the closest thing to v8’s `font-size` trick for sizing controls. [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-a-packaged-skin) has the full list.
### Level 3: edit skin source
For changes to controls, layout, or interactions, add the skin source to your project. Its components and styles become local files. [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source) covers the setup and available skins.
This is where v8’s `controlBar` config and `addChild` calls end up, and honestly it’s the better trade. Instead of `controlBar: { pictureInPictureToggle: false }`, you delete a line. Instead of subclassing a component to change its behavior, you edit the markup.
Drop `VideoSkin` and compose the [UI components](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components) yourself. `Container` is what the skin used to render for you: the box the media and controls live in. Compound parts are namespaced, so a time slider is assembled from `TimeSlider.Root`, `TimeSlider.Track`, and friends:
```tsx
import { Container, Controls, Hotkey, MuteButton, PlayButton, TimeSlider } from '@videojs/react';
import { Video, VideoPlayer } from '@videojs/react/video';
export function MyPlayer() {
return (
{/* No PiPButton, so no picture-in-picture control renders. */}
);
}
```
Those hotkey and gesture declarations are where `userActions` went. v8’s `userActions.hotkeys` was a function you wrote; here each shortcut is a component with a key and an action, and `userActions.click` and `doubleClick` become gestures with a region. The packaged skins already include a sensible set of both, which is why you don’t see them in the earlier examples.
When you add the skin source, you also take on its CSS. The packaged skins ship styles for everything above; a bare layout renders unstyled until you bring those along, so the added source includes the skin’s stylesheet next to its markup.
## Plugins
v10 has no plugin system. There’s no `videojs.registerPlugin`, no `player.myPlugin()`, and no plugin lifecycle.
That’s a deliberate choice rather than a missing feature. v8 plugins existed largely because there was no other way in: to add a control, change a behavior, or support a format, you had to reach into player internals through the one door the plugin API provided. v10 gives you the front door instead: components you can add, skin source you can change, and media elements you can swap. Most of what plugins did is now ordinary composition.
Audit your plugins and sort them into four piles:
- **Formats and techs** (`videojs-contrib-*`, YouTube, Vimeo, Mux). Replace with the matching media component. See [Techs become media components](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-video-js-8#techs-become-media-components).
- **UI additions** (extra buttons, overlays, custom control bars). Rebuild them by editing the skin source in your project, or with [your own component](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/build-your-own-component). This is usually less code than the plugin was.
- **Workarounds** for v8 limitations. Check whether the limitation still exists before you port anything.
- **Genuinely missing features** (ads, playlists). These need real work, and some have no home yet. Get them on the list early, because they’ll drive your timeline.
That last pile is the honest risk in a v8 migration. If your player depends on an ads plugin, there’s no v10 answer today.
## Read player state
### Events
Your media element is a real media element, so every event you already listen for still fires on it. The listeners port directly; only where you attach them changes.
```js
// Video.js 8
const player = videojs('my-video');
player.on('timeupdate', () => console.log(player.currentTime()));
// Video.js v10
const video = document.querySelector('video');
video.addEventListener('timeupdate', () => console.log(video.currentTime));
```
One category doesn’t survive that translation, because those were never media events. v8’s UI events (`useractive`, `userinactive`, `playerresize`, `texttrackchange`) were the player’s own. Read the equivalent from player state instead.
### Player state
Put standard media event props such as `onPlay`, `onTimeUpdate`, `onEnded`, and `onError` on `Video` or your chosen media component. Read player state through the preset’s [`usePlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-player) hook, typed to that preset’s features:
```tsx
import { usePlayer } from '@videojs/react/video';
function Elapsed() {
const currentTime = usePlayer((state) => state.currentTime);
return {currentTime} ;
}
```
Every feature has a selector (`selectPlayback`, `selectTime`, `selectVolume`, `selectQuality`, `selectLive`, `selectTextTrack`, and so on) for when you want a whole slice rather than one value.
### Drive playback
v8 used accessor methods for everything: `player.currentTime()` to read, `player.currentTime(10)` to write. v10 keeps that single-object habit: control everything through the player. Its store holds the state each feature tracks and an action for each of these calls — playback, seeking, volume, rate, fullscreen, captions, and quality alike.
You can also write to the media element directly. That is safe because player state derives from the native media events: set `media.currentTime` and the time slider follows. There is no wrapper to fall out of sync.
| Video.js 8 | Video.js v10 |
| --- | --- |
| `player.play()`, `player.pause()` | the player’s `play`, `pause`, `togglePaused`, or `media.play()`, `media.pause()` |
| `player.currentTime()` / `player.currentTime(10)` | `currentTime` in player state, the player’s `seek(10)`, or `media.currentTime` |
| `player.duration()` | `duration` in player state, or `media.duration` |
| `player.volume()`, `player.muted()` | the player’s `setVolume`, `toggleMuted`, or `media.volume`, `media.muted` |
| `player.playbackRate()` | the player’s `setPlaybackRate`, or `media.playbackRate` |
| `player.src({ src, type })` | set `src` on the media or replace the media component (`Video`, `HlsJsVideo`, `DashVideo`, etc) |
| `player.requestFullscreen()`, `exitFullscreen()` | the player’s `requestFullscreen`, `exitFullscreen`, `toggleFullscreen` |
| `player.textTracks()`, `addRemoteTextTrack()` | `` elements, and `textTrackList` in player state, `textTracks` in media |
| `player.audioTracks()` | `audioTrackList` in player state, `audioTracks` in media |
| `player.error()` | `error` in player state |
| `player.dispose()` | unmount the component |
| `player.tech()` | the media component’s public `engine` escape hatch, where one exists; reach it through `useMedia()` |
| `videojs.getPlayer(id)` | call `usePlayer` from a component inside the player |
Where v8 had you keep the `videojs()` return value in a ref, put the ref on the media component instead; its value is the rendered `HTMLVideoElement`, ready for every `media.*` entry in the table. The player’s actions come from the same `usePlayer` hook you read state with — select `togglePaused`, `setPlaybackRate`, or `toggleFullscreen` from state and call it. Where `player.tech()` habits linger, `useMedia` returns the Video.js media object.
Swapping sources is the change most likely to surprise you. There’s no `player.src()`; you set `src` on the media element, or replace the media element entirely, and the UI follows. Changing formats is changing tags.
## Languages
v8 shipped one language and asked you to register more with `videojs.addLanguage`. v10 ships locale packs for around 50 languages, so most apps need no setup at all. See [Internationalize the player](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/internationalization).
To override individual strings, use [`I18nProvider`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/i18n-provider) when you want them scoped to a subtree:
```tsx
import { I18nProvider } from '@videojs/react/i18n';
{/* … */}
```
See [Internationalize the player](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/internationalization) for scoped overrides, custom locales, and runtime switching.
## Live and audio-only
v8 turned live UI on with a `liveui` flag, and audio-only on with `audioOnlyMode`. In v10 these are different players with different skins, because live and audio-only have different state and a genuinely different UI. See [Presets](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets).
```tsx
import '@videojs/react/live-video/skin.css';
import { HlsVideo } from '@videojs/react/media/hls-video';
import { LiveVideoPlayer, LiveVideoSkin } from '@videojs/react/live-video';
```
For audio, use the audio preset, or the live audio one. There’s also a background video preset for muted, chrome-free background video, which v8 had no answer for.
You get `targetLiveWindow` and `liveEdgeStart` in state, plus a live button that jumps to the live edge. The live preset does not include `streamType`; add the stream type feature to a custom player when you need it. v8’s `liveTracker` tuning has no equivalent ([#1730](https://github.com/videojs/v10/issues/1730)).
The live composition is deliberately narrower than the video one. It leaves out playback rate, quality, and audio-track state, so those controls don’t appear in a live skin’s settings menu. If you need an omitted feature on a live player, build your own player from a feature list rather than taking the preset’s.
That’s what [`createPlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/create-player) is for. Hand it a feature list and you get back a `Player` component and a `usePlayer` hook, the same pair every preset is built from.
## Moved utilities
v8 put a handful of utilities on the `videojs` global for anyone building a custom component or plugin: `videojs.time.formatTime`, `videojs.dom`, `videojs.fn.throttle`, and a few others. There’s no global in v10, but the same job is covered by `@videojs/utils`.
| Video.js 8 | Video.js v10 |
| --- | --- |
| `videojs.time.formatTime(seconds, guide)` | `formatTime(seconds, guide)` from `@videojs/utils/time` |
| a hand-rolled remaining-time or percent string | `formatTimeAsPhrase(seconds)` and `formatPercent(fraction)`, from `@videojs/utils/time` and `@videojs/utils/percent` |
| `videojs.fn.throttle(fn, wait)` | `throttle(fn, ms)` from `@videojs/utils/function` |
| `videojs.dom.isEl(value)` and its type-specific cousins | `isHTMLVideoElement`, `isHTMLMediaElement`, `isDocument`, and other narrowing checks from `@videojs/utils/dom` |
| `videojs.obj.merge(a, b)` | `defaults(object, defaultValues)` from `@videojs/utils/object`, alongside `pick`, `omit`, `deepEqual`, and `shallowEqual` |
These are worth reaching for before writing your own when extending the player. For example, `formatTime` is the exact digital-clock formatting the packaged skins use for their own time displays, so a custom one will match. The package is split into subpaths, so you can import only the module you need. Other than `time`, it includes `array`, `events`, `i18n`, `jwt`, `predicate`, `string`, and `types` subpaths for anything else a custom component or plugin replacement needs.
Import the util function directly with a `
```
Or with a bundler:
```bash
npm install @videojs/utils
```
```js
import { formatTime } from '@videojs/utils/time';
```
## Known gaps
Ordered roughly by how likely each is to block a v8 migration.
- **No ads support.** v8’s IMA and ad-plugin ecosystem has no v10 equivalent. This is the most common hard blocker.
- **No playlist support.** No `videojs-playlist` equivalent.
- **No plugin system**, by design. Budget for rebuilding UI plugins as components. See [Plugins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-video-js-8#plugins).
- Playback rates are a fixed set — `0.2`, `0.5`, `0.7`, `1`, `1.2`, `1.5`, `1.7`, `2` — so v8’s `playbackRates` has no equivalent yet ([#1404](https://github.com/videojs/v10/issues/1404)).
- No text-track settings dialog. v8’s `textTrackSettings` let viewers restyle captions; v10 exposes only the positioning custom properties its skins define.
- No spatial navigation. v8’s `spatialNavigation` for TV and D-pad remotes has no equivalent.
- Nothing persists between sessions: volume, captions language, speed, quality. That’s out of scope for GA ([#944](https://github.com/videojs/v10/issues/944)). Default subtitle language is tracked at [#1423](https://github.com/videojs/v10/issues/1423).
- No VHS-equivalent tuning surface. Engine settings belong to the engine you chose, and the default HLS component deliberately exposes few of them.
- Chapters render in the time slider from a ``, and its segments reflect `data-active`. There is no player-level active chapter value or chapter menu, so v8’s chapters menu has no equivalent ([#1873](https://github.com/videojs/v10/issues/1873)). Cue points aren’t implemented ([#1442](https://github.com/videojs/v10/issues/1442)).
- The controls auto-hide delay isn’t configurable, so arbitrary `inactivityTimeout` values have no equivalent ([#1728](https://github.com/videojs/v10/issues/1728)). The common `inactivityTimeout: 0` case is covered by `visibility="always"` on the controls component in a custom layout or a skin layout in your project.
- No full-window fullscreen fallback. v8 had one for browsers without the Fullscreen API; [support is around 96%](https://caniuse.com/fullscreen) now.
- Multiple `` elements with `size` metadata don’t become a quality menu. Use HLS or DASH for adaptive quality; picking renditions by resolution won’t be added ([#1415](https://github.com/videojs/v10/issues/1415)).
- Two skins, and no runtime theme switch.
- Native controls are not automatically removed when custom controls load ([#1160](https://github.com/videojs/v10/issues/1160)).
- Smaller conveniences without homes yet: debug mode ([#1406](https://github.com/videojs/v10/issues/1406)) and autoplay with a muted fallback ([#1039](https://github.com/videojs/v10/issues/1039)).
## See also
- [Features](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features) and [Presets](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets)
- [Media sources](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/media-sources)
- [Skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins) and [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins)
---
# Migrate from Mux Player
Move a Mux Player embed to Video.js v10, splitting one element into a player, a media, and a skin
Mux Player combines HLS playback, UI, analytics, captions, remote playback, and keyboard shortcuts in one element. Video.js v10 composes those responsibilities from a player, media component, skin, and optional [extensions](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/architecture).
This guide moves a working Mux Player embed to those pieces, then maps the settings and APIs you are most likely to need next.
> **Tip**
>
> Did you use Mux Player without controls as a hero, ambient loop, or decorative video? Go to [Add a background video](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/background-video). It starts with a browser-playable video file, then covers the HLS and Mux background components.
## Before you migrate
A few minutes of auditing tells you which sections of this guide apply to you:
- **List the Mux Player attributes or React props you set.** Compare them with the mapping tables below to make your migration checklist.
- **Grep your codebase for `mux-player` selectors.** CSS rules and `querySelector` calls that reach into the element — `mux-player::part(…)`, `mux-player [role="slider"]`, `player.shadowRoot` — will silently stop matching after the swap. Plan to restyle with the skin’s custom properties or rebuild against Video.js components.
- **Find your event listeners and imperative calls** (`play()`, `currentTime`, `addChapters`). Media APIs move to the media element; the rest is mapped under [Drive playback](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-mux-player#drive-playback).
- **Note your theme and CSS variables.** Two skins replace Mux Player’s five themes, and `--accent-color` and friends have new names.
- **Check your catalog for DRM or TS-packaged assets.** They decide which of the two Mux media flavors you can use; see [Which Mux media should you use?](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-mux-player#which-mux-media-should-you-use).
## Three pieces instead of one
Mux Player packs three jobs into a single element. Video.js splits them up, so it helps to learn the names before you write any code.
**The player** is the outer React component. It holds state, hands that state to everything inside it, and renders no DOM of its own. Which state it holds depends on the [features](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features) it’s built from.
**The media** is the thing that plays the video. The Mux media is the one you want: it knows what a playback ID is and how to talk to Mux. Swap it for another [media component](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/media-sources) and the rest of your player keeps working.
**The skin** is the UI: the controls, the poster, the captions, the settings menu, the keyboard shortcuts. [Skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins) are pre-built arrangements of smaller components, and you can use one as-is, restyle it, or take it apart.
So a Mux Player embed becomes a player wrapped around a skin wrapped around a media:
```jsx
```
Everything else in this guide is about which of those three a Mux Player setting now belongs to.
## Your first player
Here’s a typical Mux Player embed. A playback ID, a title and viewer ID for analytics, and a poster pulled from two seconds in.
```tsx
import MuxPlayer from '@mux/mux-player-react';
export function MyPlayer() {
return (
);
}
```
`@videojs/react` gives you real React components rather than one component wrapping a custom element.
```bash
npm install @videojs/react @videojs/mux-video @videojs/mux-data
```
Start with the general-purpose `@videojs/react/video` [preset](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets), then add the Mux media and analytics components:
```tsx
'use client';
import '@videojs/react/video/skin.css';
import { VideoPlayer, VideoSkin } from '@videojs/react/video';
import { MuxData } from '@videojs/react/extensions/mux-data';
import { MuxVideo } from '@videojs/react/media/mux-video';
export function MyPlayer() {
return (
);
}
```
`VideoPlayer` is the piece that owns the state. To read that state, the preset ships a matching [`usePlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-player) hook.
The `'use client'` directive is there because the player owns browser state.
> **Caution: Analytics changes from opt-out to opt-in**
>
> Mux Player monitors playback by default. Video.js sends no Mux Data beacons unless you add the `MuxData` extension shown above. Keep it when you want a behaviorally equivalent migration; omit it only when you intend to stop monitoring.
A few things worth calling out:
- **The skin has no size of its own**, so the examples give it one with an inline `aspect-ratio`. Any styling that sizes the skin works the same way, whether that’s a class of yours or a Tailwind utility like `aspect-video`. See [Move your layout styles](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-mux-player#move-your-layout-styles).
- **The Mux media supplies the poster.** It builds the image URL from the playback ID, and the skin displays it automatically. The example keeps the frame from two seconds in by configuring the Mux media. Set `poster` on the player only when you want to use your own URL.
- **You didn’t add a storyboard track, and you get hover previews.** The Mux media adds and maintains the thumbnail track itself, and removes it for live streams, where storyboards don’t exist.
- **Analytics needs no environment key.** Mux resolves the environment from the playback ID. See [Mux Data](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/mux-data).
- **Chromecast is opt-in.** Follow [Cast to AirPlay and Chromecast](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/casting) when you want it; leave the extension out when you don’t.
### Move your layout styles
Mux Player was one visible, measurable element. Video.js separates player state from the visible surface.
If you use `VideoSkin`, put width, height, aspect ratio, positioning, and DOM measurements on `VideoSkin`. The `skin.css` import shown above makes the media, controls, poster, and overlays fill and layer within it. `VideoPlayer` renders no DOM element of its own.
If you leave out `VideoSkin` to build your own UI, add a [`Container`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/player-container). Style and measure that element, and put overlays inside it:
```tsx
import { Container } from '@videojs/react';
```
> **Note**
>
> Put standard media handlers such as `onPlay`, `onTimeUpdate`, `onEnded`, and `onError` on `MuxVideo`. Use [`usePlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-player) for player-store state. See [Read player state](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-mux-player#read-player-state).
## Mux settings live in a source object
Mux Player exposes Mux stream parameters as props such as `maxResolution`, `assetStartTime`, and `customDomain`.
Video.js collects them into a single **source** object that describes what to play and how.
```js
{
playbackId: 'EcHgOK9coz5K…',
playback: { maxResolution: '1080p', assetStartTime: 10, assetEndTime: 30 },
poster: { time: 2, width: 1280 },
}
```
The groups map to the three URLs Mux serves. `playback` modifies the video stream, `poster` modifies the still image, and `storyboard` modifies the hover-preview track. Video.js builds all three URLs and converts your camel-case keys to the `snake_case` query parameters Mux expects, so `assetStartTime` goes out as `asset_start_time`.
Pass it as the `source` prop:
```jsx
```
You can also skip the object and pass `src` a full Mux URL. The component parses it back into a source, query parameters included:
```jsx
```
There’s no `playbackId` prop of its own; it lives on `source`.
Here’s where the Mux Player React props land. Mux Player groups signing tokens in `tokens`; Video.js puts each one beside the URL it signs:
| Mux Player React | Video.js v10 |
| --- | --- |
| `playbackId` | `source.playbackId` |
| `customDomain` | `source.customDomain` |
| `maxResolution`, `minResolution` | `source.playback.maxResolution`, `.minResolution` |
| `renditionOrder` | `source.playback.renditionOrder` |
| `assetStartTime`, `assetEndTime` | `source.playback.assetStartTime`, `.assetEndTime` |
| `programStartTime`, `programEndTime` | `source.playback.programStartTime`, `.programEndTime` |
| the `default_subtitles_lang` playback parameter | `source.playback.defaultSubtitlesLang` |
| `tokens.playback` | `source.playback.token` |
| `tokens.thumbnail`, `tokens.storyboard` | `source.poster.token`, `source.storyboard.token` |
| `tokens.drm` | `source.drm.token` |
| `thumbnailTime` | `source.poster.time` |
| poster URL size, crop, rotation, format | `source.poster.width`, `.height`, `.fitMode`, `.rotate`, `.ext` |
Signed playback behaves the way it does in Mux Player: a token replaces every other parameter in its group, so caps and clipping have to be baked into the token itself.
## Analytics moves to its own extension
Mux Player’s analytics settings become props on the [Mux Data extension](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-data), placed inside the player.
| Mux Player | Video.js v10 |
| --- | --- |
| `metadata={…}` | the `metadata` prop |
| `envKey` | `envKey`, rarely needed for Mux-hosted content |
| `disableCookies` | `disableCookies` |
| `beaconCollectionDomain` | `beaconCollectionDomain` |
| `playerSoftwareName`, `playerSoftwareVersion` | `playerSoftwareName`, `playerSoftwareVersion` |
| `debug` | `debug` |
| `disableTracking` | omit the component |
Your metadata keys don’t change. They’re the same `snake_case` names Mux Data has always taken, so the values port across untouched.
## Titles and posters
Mux Player used the same title for analytics and on-screen display. Video.js separates them.
For analytics, use `metadata.video_title` on the Mux Data extension.
For display, use `title` on the player.
An asset titled in the Mux dashboard supplies its own: the Mux media loads the asset’s metadata and the player falls back to that title when none is set on it, so the display title is optional for Mux-hosted video.
The packaged video and live-video skins show the resolved title at the top of the player and fade it with the controls, so the embeds above already display it. The [Title](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/title#styling) component sets `data-visible` while the controls are visible, so your skin overrides can move it differently. The audio skins have no title display.
A skin layout you added to your project, or a custom layout, shows the title only where you place it. Keep it inside the sized container from [Move your layout styles](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-mux-player#move-your-layout-styles) so it overlays the media:
```tsx
import { Container, Title } from '@videojs/react';
import { MuxVideo } from '@videojs/react/media/mux-video';
import { VideoPlayer } from '@videojs/react/video';
```
`MuxVideo` supplies a poster from the playback ID, and `source.poster` controls the generated image. The skin displays it automatically. Pass `poster` to the player when you want to use your own URL:
A generated poster becomes available after `MuxVideo` mounts. Pass `poster` to `VideoPlayer` when the image must appear in server-rendered HTML.
```jsx
}
>
```
`renderPoster` customizes the poster image, so its background can show Mux Player’s `placeholder` while the real poster loads.
Mux serves the poster from its `thumbnail` endpoint, and `source.poster` configures that URL: `thumbnail-time` is `source.poster.time`, and the size, crop, rotation, and format options are `width`, `height`, `fitMode`, `rotate`, and `ext` beside it. Video.js converts those camel-case keys to the `snake_case` query parameters Mux expects. See [Add a poster and loading placeholder](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/poster) for more examples or the [Poster](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/poster) reference for the component itself.
## Customize your player
Mux Player gives you attributes and documented CSS variables. Past that, you’re stuck. Video.js gives you three levels, and you should try them in order.
### Level 1: pick a skin
Two are packaged. The default skin is a modern, frosted look. The minimal skin is closer to a classic control bar. Both bring controls, tooltips, captions, keyboard shortcuts, touch gestures, and a settings menu that appears when there’s something to put in it. See [Skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins).
### Level 2: restyle it
Set custom properties on the skin. The common case is a brand color:
Give the skin a class you own:
```tsx
...
```
```css
.my-player-skin {
--media-accent-color: rebeccapurple;
}
```
`--media-accent-color` reaches the sliders, the active buttons, and the accent surfaces. Video.js derives a readable text color to sit on top of it; override that with `--media-accent-text-color` if you’d rather choose. `--media-border-radius` rounds the player, and `--media-scale-unit` scales the whole control bar at once. [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-a-packaged-skin) has the full list.
The skins use a different visual design, so you may not need to replace Mux Player’s `primaryColor` and `secondaryColor` directly. Start with `--media-accent-color`. Restyle individual surfaces, or add the skin source to your project, only when you need a closer palette match.
### Level 3: edit skin source
For changes to controls, layout, or interactions, add the skin source to your project. Its components and styles become local files. [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source) covers the setup and available skins.
This is the level that per-control tweaks need, and it’s a genuine step up in effort from a Mux Player attribute. `forward-seek-offset="30"` was one character. In Video.js, the skins bake their seek step into their keyboard shortcuts and gestures, so changing it means editing those lines:
```tsx
```
While you’re in there: neither packaged video skin includes skip *buttons*. Mux Player’s themes show them, so if your users expect them, add a [seek button](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/seek-button), which takes `seconds` and defaults to 30.
Removing a control is removing a line. That’s the trade you get for the extra setup.
## Read player state
Standard media event props port directly to `MuxVideo`: `onPlay`, `onTimeUpdate`, `onEnded`, and `onError` work on the rendered video element. Read player-store state through the preset’s [`usePlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-player) hook, typed to that preset’s features:
```tsx
import { usePlayer } from '@videojs/react/video';
function Elapsed() {
const currentTime = usePlayer((state) => state.currentTime);
return {currentTime} ;
}
```
Every feature has a selector (`selectPlayback`, `selectTime`, `selectVolume`, `selectQuality`, `selectLive`, `selectTextTrack`, and so on) for when you want a whole slice rather than one value.
The pair works exactly like React Context: `Player` is the Provider, and `usePlayer` is its `useContext`-style consumer, so it only works inside `Player`. If a component that needs player state renders outside `Player`, lift `Player` above it the way you’d lift any Provider. It renders no DOM, so wrapping a page or layout in it changes nothing visually and puts the store in reach of everything inside.
Use a ref for imperative browser media APIs or for custom events that do not have React event props, such as `sourcechange`. The ref value is the rendered `HTMLVideoElement`.
### Drive playback
| Mux Player | Video.js v10 |
| --- | --- |
| `player.play()`, `player.pause()` | the player’s `play`, `pause`, `togglePaused`, or `media.play()`, `media.pause()` |
| `player.currentTime = 10` | the player’s `seek(10)`, or `media.currentTime = 10` |
| `player.volume`, `player.muted` | the player’s `setVolume`, `toggleMuted`, or `media.volume`, `media.muted` |
| `player.playbackRate` | the player’s `setPlaybackRate`, or `media.playbackRate` |
| `player.requestFullscreen()` | the player’s `requestFullscreen`, `exitFullscreen`, `toggleFullscreen` |
| `player.addChapters([…])` | a ``, covered below |
Control everything through the player: “the player’s” entries are store actions, reached the same way you read state above. Setting a standard media property directly works too — player state derives from the native media events, so the UI stays in sync either way.
## Which Mux media should you use?
You can skip this section until you hit one of the two problems in it.
`MuxVideo` comes in two flavors, backed by two different playback engines, and the import path chooses between them. Start with the default. The tradeoff: the `/spf` flavor is smaller and the `/hls-js` flavor is more compatible:
| Import | Engine | When |
| --- | --- | --- |
| `.../media/mux-video` | hls.js | **The default. Start here.** |
| `.../media/mux-video/spf` | SPF | You want a much smaller bundle and neither problem below applies. |
| `.../media/mux-video/hls-js` | hls.js | You want to pin hls.js, and reach its instance and settings. |
SPF is Video.js’s own playback engine, and it’s the reason v10 can be as small as it is. It doesn’t do two things hls.js does:
- **TS-packaged media.** Some Mux assets are packaged as TS rather than CMAF. If any of your catalog is, stay on the default.
- **DRM.** SPF doesn’t license protected content.
All three imports provide a `MuxVideo` component with the same source API, so changing the engine is an import change. React components do not register a custom element, and different imports can coexist if separate players need different engines.
The default doesn’t promise which engine it uses, which is what leaves it free to change. Import `/hls-js` if your app depends on hls.js being the one. Otherwise take the default: it plays everything.
The Mux audio component follows the same three paths, and pairs with the audio player and audio skins.
## Live streams
Unlike Mux Player, you’ll have to pick a live preset yourself; it won’t switch automatically for you.
```tsx
import '@videojs/react/live-video/skin.css';
import { LiveVideoPlayer, LiveVideoSkin } from '@videojs/react/live-video';
import { MuxVideo } from '@videojs/react/media/mux-video';
```
You get `targetLiveWindow` and `liveEdgeStart` in player state, plus a live button that jumps to the live edge. The live preset doesn’t include `streamType` state and doesn’t force a source to be live. The Mux media detects the manifest: `targetLiveWindow` is `NaN` for an on-demand or unknown source, `0` for a sliding live window, and `Infinity` for a live event with playback history. See [the live feature](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-live).
The live composition is narrower than the video one on purpose: it leaves out quality, audio-track, and playback-rate state. A live skin’s settings menu therefore holds captions and nothing else. If you need one of the omitted features on a live player, build your own player from a feature list rather than taking the preset’s.
Use [`createPlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/create-player) to create a `Player` component and matching `usePlayer` hook.
### Add your own jump-to-live button
The live skin already includes a live button. If you build your own controls, use that same component and style it to match your app. It keeps track of whether playback is live and returns viewers to the newest available point in the stream.
```tsx
import { LiveButton } from '@videojs/react';
On air
```
Do not rebuild this behavior from `duration` or set `currentTime` to `Infinity`.
### Troubleshoot live playback
#### An on-demand video shows live controls
Video.js does not replace the preset after reading the HLS playlist. Render the video preset for on-demand content and the live preset for live content. If the same part of your app handles both, choose the preset from application or content metadata before rendering. If only the manifest can tell you, use a custom player with the stream type feature and choose the controls from that state.
#### `selectStreamType` returns `undefined`
The live preset does not include the [stream type feature](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-stream-type). Add `streamTypeFeature` to a custom player when you need `streamType` in player state.
The HLS media object also reads `'live'` or `'on-demand'` from the playlist. Get that object with `useMedia`.
#### A live stream has a finite duration
The browser may report `Infinity` for live playback, but the player’s [time feature](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/feature-time) reports the end of the available video. That number stays finite and moves forward with the stream.
Do not use `duration` to decide whether a source is live. Read `streamType`, or check that `targetLiveWindow` is not `NaN`.
#### `targetLiveWindow` does not match the rewind time
Despite its name, `targetLiveWindow` does not report a number of seconds. It describes the kind of live stream:
| Value | Meaning |
| --- | --- |
| `0` | A sliding live window |
| `Infinity` | A live event with playback history |
| `NaN` | On-demand or not known yet |
To find the times a viewer can seek to, read `buffer.seekable`. It contains `[start, end]` pairs. The first start is the oldest available time, and the last end is the newest. Both move forward on a sliding live stream.
`liveEdgeStart` is the playback time where the player starts treating the viewer as live. The live button seeks to the last end in `buffer.seekable`, which may be later than `liveEdgeStart`.
## The settings menu
On a video player, the settings menu appears on its own when there’s something to put in it:
| What | Component | Notes |
| --- | --- | --- |
| Quality | [Quality radio group](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/quality-radio-group) | Lets a viewer pick the video quality. To set the highest available quality instead, use `source.playback.maxResolution`. |
| Audio tracks | [Audio track radio group](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/audio-track-radio-group) | For multi-language audio. |
| Captions | [Captions radio group](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/captions-radio-group) | Rendered by the browser. |
| Speed | [Playback rate radio group](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/playback-rate-radio-group) | The rates are a fixed set — `0.2`, `0.5`, `0.7`, `1`, `1.2`, `1.5`, `1.7`, `2` — and you can’t choose your own yet ([#1404](https://github.com/videojs/v10/issues/1404)). |
Caption *styling* is limited to the positioning custom properties the skins expose. There’s no equivalent of a text-track settings dialog.
## Chapters and cue points
Chapters are content, not an API call. Add a chapters track inside your media and the skins segment the [time slider](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/time-slider) and show the chapter title on hover:
```jsx
```
There’s no `addChapters()`. If you were building that VTT on the fly, you’ll still need to, but you point the player at it instead of passing an array ([#1268](https://github.com/videojs/v10/issues/1268)).
The time slider marks the segment containing the current playback time with `data-active`, so you can style the active segment. The player still has no active-chapter state, `chapterchange` event, or menu for jumping between chapters ([#1873](https://github.com/videojs/v10/issues/1873)). If UI outside the time slider needs the current chapter, derive it from `currentTime` and the read-only `chaptersCues` array. Cue points aren’t implemented at all ([#1442](https://github.com/videojs/v10/issues/1442)).
## Signed playback and DRM
**Signed playback works today.** Follow Mux’s [secure video playback guide](https://www.mux.com/docs/guides/secure-video-playback) to create a signing key and generate these tokens on your server. Each token is a parameter in its own group, and Video.js checks each one’s audience before building a URL, so a token in the wrong slot produces no URL rather than a request Mux would reject:
```js
{
playbackId: 'EcHgOK9coz5K…',
playback: { token: '…' }, // audience: v
poster: { token: '…' }, // audience: t
storyboard: { token: '…' }, // audience: s
}
```
Signed playback needs its own poster token even when the Mux media would otherwise derive the poster from the playback ID. Put Mux’s thumbnail token at `source.poster.token`. If it is missing or has the wrong audience, the media cannot build a poster URL.
Neither player refreshes tokens. Mux Player at least notices an expired one and shows a friendly message; Video.js doesn’t surface that yet ([#1432](https://github.com/videojs/v10/issues/1432)).
**DRM works on the default Mux media** and on native HLS. Hand it a license token and Video.js derives the FairPlay, Widevine, and PlayReady license servers from it, along with the FairPlay application certificate:
```js
{
playbackId: 'EcHgOK9coz5K…',
playback: { token: '…' },
drm: { token: '…' }, // audience: d
}
```
DRM playback is always signed, so `drm.token` needs a `playback.token` beside it. For content Mux doesn’t license, name license servers yourself, keyed by key system; yours win over the derived ones key by key.
The SPF flavor doesn’t license DRM ([#1776](https://github.com/videojs/v10/issues/1776)), which is one of the two reasons to stay on the default import.
## Access the media and playback engine
| Mux Player | Video.js v10 |
| --- | --- |
| `media.nativeEl` | `ref.current` from a `ref` on the media component |
| the Video.js media object | `useMedia()` inside the player |
| the hls.js instance | the media object’s `.engine`, reached through `useMedia`, on the hls.js-backed flavor |
| `prefer-playback` | `source.preferPlayback`, or pick [native HLS](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/native-hls-video) outright |
`source.preferPlayback` is the closest mapping: set it to `'native'` and the Mux media hands playback to the browser’s own HLS support instead of building an MSE pipeline, which is what `prefer-playback="native"` did.
> **Caution: Treat engine access as an escape hatch**
>
> Reading `.engine` couples your app to hls.js and the `/hls-js` flavor. Prefer Video.js state, events, and media APIs when they cover your use case. Reach into the engine only for functionality Video.js doesn’t expose.
The media component’s React ref is the native `HTMLVideoElement`; it has no `.target` or `.host`. Use the player context for the Video.js media object:
```tsx
import { useMedia } from '@videojs/react';
function EngineAccess() {
const media = useMedia();
const engine = media && 'engine' in media ? media.engine : null;
// `engine` is the active hls.js instance for the `/hls-js` flavor.
return null;
}
```
Import the `/hls-js` flavor when your app depends on that engine. The default flavor deliberately doesn’t promise which engine it uses.
Program Date Time has no convenience surface: no `getStartDate()`, no `currentPdt`. The player exposes `liveEdgeStart` and `targetLiveWindow`; for PDT itself, reach into the engine.
## Known gaps
Ordered roughly by how many migrations they’ll touch.
- Two skins, against Mux Player’s five themes, and no runtime theme switch. That’s a deliberate trade, fewer skins whose files you can add to your project, but it’s a real difference if you shipped `theme="classic"`.
- Lazy loading (`loading="viewport|page"`) has no equivalent.
- The controls auto-hide delay isn’t configurable ([#1728](https://github.com/videojs/v10/issues/1728)). Always-visible controls are available through `visibility="always"` on the controls component in a custom layout or a skin layout in your project.
- Nothing persists between sessions: volume, captions language, speed, quality. That’s out of scope for GA ([#944](https://github.com/videojs/v10/issues/944)). Default subtitle language is tracked at [#1423](https://github.com/videojs/v10/issues/1423), though Mux users can set `source.playback.defaultSubtitlesLang` and let the HLS playlist decide.
- Smaller conveniences without homes yet: debug mode ([#1406](https://github.com/videojs/v10/issues/1406)) and autoplay with a muted fallback ([#1039](https://github.com/videojs/v10/issues/1039)). Unmuting from zero volume already restores a sensible level, so Mux Player’s smart-unmute behavior carries over.
## See also
- [Mux Video](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-video) and [Mux Audio](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/mux-audio)
- [Mux Data](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/mux-data)
- [Skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins) and [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins)
---
# Migrate from Plyr
Move an existing Plyr integration to Video.js v10, mapping Plyr options and its instance API onto components and player state
Video.js v10 is not a drop-in replacement for Plyr. Plyr wraps one media element with a constructor and options object. Video.js composes a player, media component, and skin in markup, then exposes behavior through [player state](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features).
Start with the Minimal skin, move media settings into markup, and replace calls to the Plyr instance with native media APIs or Video.js state actions.
## What changes
- **The player becomes three pieces.** Player state, the media component, and the skin are separate, so you can replace one without wrapping or forking the others.
- **Streaming behavior becomes player state.** HLS, DASH, and Mux integrations expose renditions, tracks, and live state to the UI instead of leaving that wiring to application code.
- **React uses native components and hooks.** `@videojs/react` owns its lifecycle instead of wrapping an imperative constructor around framework-owned DOM.
- **The UI is composable.** Buttons, sliders, menus, gestures, and hotkeys are individual accessible components. Start with the Minimal or Default skin, then [add its source to your project](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr#edit-skin-source) when you need to change the structure.
- **Remote playback is built in.** The video skins include AirPlay and Cast controls. Follow [Cast to AirPlay and Chromecast](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/casting) to add the Google Cast extension.
> **Note**
>
> Video.js v10 is still moving toward GA. Features like ads, playlists, preference persistence, and cue-point APIs are active areas, so check [Known gaps](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr#known-gaps) when those features matter to your migration.
## Basic migration
Start with a Plyr player that has captions, thumbnail previews, and a poster:
```html
```
The Minimal skin is the closest built-in starting point for this migration.
First, install the dependency:
```bash
npm install @videojs/react
```
Then create a reusable player component in your app:
```tsx
'use client';
import '@videojs/react/video/minimal-skin.css';
import { MinimalVideoSkin, Video, VideoPlayer } from '@videojs/react/video';
interface AppVideoPlayerProps {
origin: string;
}
export function AppVideoPlayer({ origin }: AppVideoPlayerProps) {
return (
);
}
```
### Notes
- `@videojs/react/video` is a [preset](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets): a player, a skin, and a media element that already fit together. `VideoPlayer` is the piece that owns the state, built from the standard set of [features](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features) for video.
- The poster URL is metadata on `VideoPlayer`. The skin reads that metadata and controls how the poster appears. To replace the rendered image, pass `renderPoster` to the skin — see [Add a poster and loading placeholder](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/poster).
- This example assumes all your files for a given asset live in the same path, using consistent filenames. This will almost certainly need adjusting for your implementation.
- If `origin` points somewhere other than your page’s origin, add `crossOrigin="anonymous"` to `` and serve those files with CORS headers. A cross-origin thumbnail track only loads when the media element is CORS-enabled. See [Thumbnail](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/thumbnail).
- There’s also a default skin with a modern, frosted appearance that some may prefer. Try it by switching the CSS import filename to `skin.css` and the `MinimalVideoSkin` import and usage to `VideoSkin`.
## Map common features
### Streaming
If you’re using HLS or DASH to stream your media, you’re in luck; we have prebuilt [media components](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/media-sources) you can slot in with much improved integration over Plyr implementations.
#### HLS
Replace `` with `` and add the import:
```bash
npm install @videojs/react @videojs/spf
```
```js
import { HlsVideo } from '@videojs/react/media/hls-video';
```
Set the `src` to the URL for the m3u8 manifest.
#### DASH
Very similar to HLS in that we have a drop-in component.
Replace `` with `` and update your import:
```bash
npm install @videojs/react @videojs/dash-video
```
```js
import { DashVideo } from '@videojs/react/media/dash-video';
```
Set the `src` to the URL for the mpd manifest.
### Vimeo
Vimeo is supported through a prebuilt component.
Replace `` with `` and add the import:
```bash
npm install @videojs/react @videojs/vimeo-video
```
```js
import { VimeoVideo } from '@videojs/react/media/vimeo-video';
```
Set the `src` to the URL for the Vimeo video, for example `https://vimeo.com/76979871`.
### YouTube
YouTube is supported through a first-class media component.
Replace `` with `` and add the import:
```js
import { YouTubeVideo } from '@videojs/react/media/youtube-video';
```
```jsx
```
The component accepts YouTube watch, short, embed, Shorts, live, playlist, and privacy-enhanced URLs, as well as raw 11-character video IDs.
### Internationalization
Video.js v10 ships with English labels by default and includes locale packs for:
`ar`, `az`, `bg`, `bn`, `bs`, `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`, `ne`, `nl`, `nn`, `oc`, `pl`, `pt-BR`, `pt-PT`, `ro`, `ru`, `sk`, `sl`, `sr`, `sv`, `te`, `th`, `tr`, `uk`, `vi`, `zh-CN`, and `zh-TW`.
The shorthand tags `pt` and `zh` are also available as aliases. See [Internationalize the player](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/internationalization) for the full picture.
Use the React provider when you want scoped overrides:
```tsx
'use client';
import '@videojs/react/video/minimal-skin.css';
import { I18nProvider } from '@videojs/react/i18n';
import { MinimalVideoSkin, Video, VideoPlayer } from '@videojs/react/video';
export function MyPlayer() {
return (
);
}
```
## Configuration
Plyr uses an object to set configuration options whereas Video.js v10 uses a component structure and attributes instead. We’re using a composition model rather than a configuration model. This reduces bundle size and only includes functionality you actually require.
Here’s a matrix for configuration options in Plyr and how each maps to Video.js v10:
| Plyr option | Video.js v10 |
| --- | --- |
| `controls` | The [skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins) include the common controls, laid out in a familiar way that users would expect. Not every Plyr control ships in every skin—the video skins do not include `rewind` and `fast-forward` buttons, for example. To change which controls appear, or to customize the skin beyond basic colors, [add the skin source to your project](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr#edit-skin-source) and change controls, layout, styles, or icons. |
| `rewind`, `fast-forward`, `seekTime` | The audio skins include 10-second skip buttons; the video skins do not. [Add the skin source to your project](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr#edit-skin-source), then add a [seek button](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/components/seek-button), which skips by its `seconds` value (default `30`; negative values seek backward). |
| `settings` | Included automatically in the skins when quality, speed, audio tracks, or captions are available. |
| `autoplay`, `muted`, `loop`, `playsinline`, `preload` | These are attributes on your media (e.g. ``) component. |
| `poster` / `data-poster` | Set `poster` on the player. See [Basic migration](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr#basic-migration). |
| `ratio` | Set `aspect-ratio` in CSS on the skin component. |
| `hideControls` | Preset skins auto-hide controls based on activity. `hideControls: false` maps to `visibility="always"` on the controls component in a custom or installed skin layout; the delay is currently not configurable. |
| `clickToPlay` | Preset video skins include click and tap gestures. [Add the skin source to your project](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr#edit-skin-source) to remove or change them. |
| `keyboard` | Preset video skins include common hotkeys. [Add the skin source to your project](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr#edit-skin-source) to remove or change them. |
| `tooltips` | Preset skins include tooltips for common controls. [Add the skin source to your project](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr#edit-skin-source) to customize them. |
| `captions` | Add `` or ``; preset skins show captions controls when tracks are available. |
| `previewThumbnails` | Add ``; preset video skins show slider thumbnails when thumbnail cues are available. |
| `quality` | Works when the media provider exposes renditions. Plain MP4 source arrays do not currently become a quality menu automatically. |
| `speed` | Included in the preset settings menu when playback rates are available. |
| `fullscreen` | Native fullscreen is supported; Plyr’s full-window fallback is not a matching feature. |
| `provider: 'vimeo'` | Use the Vimeo media component inside the player skin as shown in [Vimeo](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr#vimeo) above. |
| `provider: 'youtube'` | Use the YouTube media component inside the player skin as shown in [YouTube](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr#youtube) above. |
| `storage` | Unsupported at this time. |
| `i18n` | The most common languages are available by default but you can also provide custom translations, if required. See [Internationalization](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr#internationalization) above for more info. |
| `ads` | Unsupported at this time. |
## Customize the controls
Plyr’s `controls` option chooses which controls appear. Video.js skins come with their own control set and layout. Keep the skin when that UI fits your player. To remove, reorder, or restyle its controls, [add the skin source to your project](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr#edit-skin-source) and edit it. Adding a child to a skin does not place it inside the control bar.
If your app already has a custom control bar, build it from individual [UI components](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components). Video.js handles the media action, accessible name, and state. You add the visible contents, layout, and CSS.
Individual React buttons do not include visible content. Use their `render` props to add an icon or text and style the element you return. Add the files for a ready-made skin when you need to change its control set or layout.
## Use the imperative API
Control everything through the player’s store. Every Plyr call has a matching store action, so one mental model covers playback, volume, fullscreen, and captions alike:
| Plyr | Video.js v10 store action |
| --- | --- |
| `player.play()`, `player.pause()` | `play()`, `pause()`, or `togglePaused()` |
| `player.currentTime = 10` | `seek(10)` |
| `player.volume = 0.5` | `setVolume(0.5)` |
| `player.muted = true` | `toggleMuted()` |
| `player.speed = 1.5` | `setPlaybackRate(1.5)` |
| `player.fullscreen.enter()` | `requestFullscreen()` |
| `player.toggleCaptions()` | `toggleSubtitles()` |
You can still script the media element directly when you want to. Plyr routed calls through its wrapper because the wrapper had to know about every change; Video.js derives player state from the native media events, so `video.play()` or `video.currentTime = 10` keeps every control in sync. The media element is also the way to change content: set `src` on the media component to swap sources, and replace the component when the media type changes, such as moving from `Video` to `HlsVideo`. The player UI follows the attached media.
Import the preset’s [`usePlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-player) hook and call it from a descendant of `VideoPlayer`. The component that creates `VideoPlayer` cannot also consume its context, so put store access in a child component:
```tsx
import '@videojs/react/video/minimal-skin.css';
import { MinimalVideoSkin, usePlayer, Video, VideoPlayer } from '@videojs/react/video';
function CurrentTime() {
const currentTime = usePlayer((state) => state.currentTime);
return {Math.round(currentTime)} seconds ;
}
export function AppVideoPlayer() {
return (
);
}
```
The same hook selects actions: `usePlayer((state) => state.togglePaused)` returns a function you can call from your own UI.
When you need the element itself, put a `ref` on the media component; its value is the rendered `HTMLVideoElement`, so `ref.current.play()` works the way Plyr’s underlying element did. For the Video.js media object, call `useMedia` from a component inside the player; media that wrap a playback engine expose it there through the `engine` escape hatch.
## Rewrite styles
Video.js v10 skins offer similar color customization via CSS custom properties. [Add the skin source to your project](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr#edit-skin-source) when you need deeper control over layout, control structure, icons, or interaction styling.
```css
/* Plyr */
.plyr {
--plyr-color-main: rebeccapurple;
}
```
```css
/* Video.js React: the className from the basic example */
.app-video-player {
--media-accent-color: rebeccapurple;
}
```
`--media-accent-color` reaches the sliders, active buttons, and accent surfaces, so it’s the closest match for Plyr’s `--plyr-color-main`. Video.js picks a readable text color to sit on top of it; set `--media-accent-text-color` to choose that yourself. `--media-border-radius` and `--media-scale-unit` cover rounding and control sizing. See [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-a-packaged-skin) for the full list.
## Edit skin source
For changes to controls, layout, or icons, add the skin source to your project. Its components and styles become local files. [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source) covers the setup and available skins.
## Known gaps
- Plyr’s `ads` option has no built-in equivalent.
- Plyr’s `storage` option has no built-in equivalent for persisted volume, captions language, muted state, speed, or quality. Player setting persistence is tracked in [#944](https://github.com/videojs/v10/issues/944); subtitle language preference is tracked in [#1423](https://github.com/videojs/v10/issues/1423).
- Plyr’s full-window fullscreen fallback has no matching Video.js feature. This was designed as a fallback when the Fullscreen API wasn’t supported, but given [browser support for fullscreen is around 96%](https://caniuse.com/fullscreen), it’s unlikely to be required.
- Plain MP4 source arrays with `size` metadata do not automatically create a quality menu. Use Mux, HLS, or DASH for adaptive quality when possible. A simpler source-driven quality menu may be considered later.
- Preset skins segment the time slider and show chapter titles when the media includes a default ``. Dedicated cue-point APIs are not complete yet; see [#1442](https://github.com/videojs/v10/issues/1442).
- The controls auto-hide delay is not configurable yet ([#1728](https://github.com/videojs/v10/issues/1728)). Disabling auto-hide is possible with `visibility="always"` on the controls component, but not from a preset skin’s attributes.
- Native controls are not automatically removed when custom controls load; see [#1160](https://github.com/videojs/v10/issues/1160).
## Related pages
### Guides
- [Features](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features): The state and actions each feature adds to the player
- [Media sources](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/media-sources): Set what a media element plays and how its engine plays it with the structured source property
- [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins): Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions
---
# Migrate from Media Chrome
Map Media Chrome's controller, elements, and attributes onto Video.js v10, where most of the work is renaming and reshaping rather than rewriting
Video.js v10’s React components mirror Media Chrome’s elements — `media-play-button` becomes `PlayButton` — so most of the work is **renaming and reshaping**, not rewriting.
> **Note**
>
> Scoped to apps that compose their own player from Media Chrome elements. If you use ``, follow the Mux Player migration guide instead.
## Before you begin
Install Video.js and choose a [preset](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets) (see [Installation](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/react)). Start with its ready-made skin if those controls fit your player. If you need to keep a custom control bar, build it from the individual Video.js UI components instead.
```bash
npm install @videojs/react
```
## Map the controller
Media Chrome wraps a slotted `` in a single ``. Video.js splits that into two components. The player owns state and draws nothing. The container is the box everything lives in, with the media as a plain child.
```html
```
Media Chrome’s React package wraps its custom elements. `@videojs/react` ships native components instead. `VideoPlayer` comes from the video [preset](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets), and `Container` is the box the media and controls live in:
```tsx
'use client';
import { Container, PlayButton } from '@videojs/react';
import { Video, VideoPlayer } from '@videojs/react/video';
export function MyPlayer() {
return (
(
{state.paused ? Play : Pause }
)}
/>
);
}
```
A preset player carries a fixed set of [features](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/features). When you need a different set, build your own with [`createPlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/create-player). Hand it a feature list and you get back a typed `Player` component and `usePlayer` hook, the same pair the preset is made of. Call it once, outside your component, and reuse it.
```tsx
import { createPlayer } from '@videojs/react';
import { videoFeatures } from '@videojs/react/video';
const { Player } = createPlayer({ features: videoFeatures });
```
Read player state with [`usePlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-player), `useMedia`, and [`useStore`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-store). Player hooks must run in a descendant component rendered inside `VideoPlayer` or the `Player` returned by `createPlayer`. A hook in the same component that returns the provider is still outside that provider.
## Map controller attributes
Media Chrome configures behavior through `` attributes. Video.js v10 has no single controller component, so these settle into three places:
- **Player features** — playback behavior that comes from the player’s feature set. A preset picks one for you; `createPlayer` lets you name your own.
- **`Container` and `Controls`** — layout, focus, and autohide.
- **Dedicated components** — `Hotkey`, `Gesture`, and friends, rendered inside the player.
| Media Chrome attribute | Video.js v10 | How |
| --- | --- | --- |
| `audio` | the audio preset | Choose an audio player and audio skin rather than toggling at runtime. |
| `autohide` | `Controls` (built in) | Controls auto-hide after inactivity automatically. `autohide="-1"` becomes `visibility="always"` on `Controls.Root`; the delay is currently fixed, see [Known gaps](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-media-chrome#known-gaps). |
| `fullscreenelement` | `Container` | Fullscreen targets the container element. |
| `gesturesdisabled` | `Gesture disabled`, or omit | Disable per gesture component, or leave the gestures out. |
| `nohotkeys` | `Hotkey disabled`, or omit | Disable per hotkey component, or leave them out. |
| `hotkeys="noarrowleft …"` | individual `Hotkey` | Each shortcut is its own component, so remove the ones you don’t want. |
| `keyboardforwardseekoffset`, `keyboardbackwardseekoffset` | `value` on `Hotkey` | Set the signed seek amount per component. |
| `defaultsubtitles` | `` for authored tracks | Add `default` to an authored captions or subtitles track. Tracks discovered from a provider or manifest don’t have one generic player-level default flag. |
| `defaultstreamtype` | `streamType` feature | Partial: derived from the media, with no pre-load default. |
| `liveedgeoffset`, `seektoliveoffset` | live media engine | Live-edge behavior lives in the playback engine, not a UI attribute. |
| `lang` | i18n translator | Localization is configured through the [translator and locale registry](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/internationalization). |
### Hotkeys
Media Chrome toggles keyboard shortcuts with `nohotkeys` and `hotkeys`. Video.js declares each shortcut as its own component, so you opt in to exactly the keys you want and set seek offsets inline:
```tsx
import { Hotkey } from '@videojs/react';
```
To drop a shortcut, remove its component or pass `disabled`. There’s no global “all hotkeys off” switch; omit the components you don’t need.
### Gestures
`gesturesdisabled` becomes per-component `Gesture` controls. Tap and double-tap behavior — click to toggle play, double-tap to seek or go fullscreen — is declared explicitly:
```tsx
import { Gesture } from '@videojs/react';
```
Remove a component or pass `disabled` to turn a gesture off.
## Map the elements
Most names carry over as PascalCase components without the `media-` prefix. These are the renames that bite:
| Media Chrome | Video.js v10 | Note |
| --- | --- | --- |
| `media-controller` | a player plus `Container` | one element becomes two: state and layout |
| `media-control-bar` | `Controls.Root`, `Controls.Group` | grouping |
| `media-time-range` | `TimeSlider` | “range” becomes “slider” |
| `media-volume-range` | `VolumeSlider` | “range” becomes “slider” |
| `media-time-display`, `media-duration-display` | `Time.Value` | one component, set via `type` |
| `media-loading-indicator` | `BufferingIndicator` | rename |
| `media-poster-image` | `Poster` | rename, and the image source moves — see below |
| `media-seek-backward-button`, `media-seek-forward-button` | `SeekButton` | one component, direction via signed `seconds` |
| `media-rendition-menu` | `QualityRadioGroup` | inside `Menu` |
| `media-captions-menu` | `CaptionsRadioGroup` | inside `Menu` |
| `media-playback-rate-menu` | `PlaybackRateRadioGroup` | inside `Menu` |
| `media-audio-track-menu` | `AudioTrackRadioGroup` | inside `Menu` |
Unchanged names, in PascalCase: `PlayButton`, `MuteButton`, `FullscreenButton`, `PiPButton`, `AirPlayButton`, `CastButton`, `CaptionsButton`, `PlaybackRateButton`, `Tooltip`, and `Thumbnail`.
> **Caution**
>
> Matching names do not mean matching appearance. Media Chrome buttons include default icons and styles. Individual Video.js buttons provide behavior, state, and an accessible name, but no visible content or finished styling. Add text or an SVG, plus your own CSS. Without visible content, a button can work while showing nothing. Sliders also need their child parts and CSS. Use a ready-made skin when you want finished controls.
React buttons do not include visible content either. Use a button’s `render` prop to add it, as shown in [Map the controller](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-media-chrome#map-the-controller). Build sliders from parts such as `TimeSlider.Track`, `TimeSlider.Fill`, and `TimeSlider.Thumb`, then add your own CSS.
Compound parts are namespaced under their component, such as `TimeSlider.Track`. See the [UI components](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components) concept for the full set.
`Poster` is the one rename that changes shape. Put the poster URL on `VideoPlayer`; `Poster.Root` owns its state and `Poster.Image` accepts image attributes such as `alt`, `srcSet`, and `sizes`:
```tsx
```
## Rewrite your styles
Media Chrome reflects state as `media*` attributes such as `mediapaused`; Video.js uses `data-*`.
```css
/* Media Chrome */
media-play-button[mediapaused] .play-icon { display: inline; }
```
```css
/* Video.js React: target the className on your rendered button */
.play-button[data-paused] .play-icon { display: inline; }
```
Continuous values use CSS custom properties: sliders expose `--media-slider-fill` and `--media-slider-pointer`.
### Map theme variables by meaning
Media Chrome and Video.js both use names beginning with `--media-`, but that shared prefix is a naming convention, not a compatibility layer. Keep a variable only when its documented meaning matches.
| Media Chrome theme variable | Packaged Video.js skin | Migration |
| --- | --- | --- |
| `--media-accent-color` or `--media-range-bar-color` | `--media-accent-color` | Closest match for slider fills and accented controls. |
| `--media-primary-color` | no direct equivalent | Often colors every control icon in Media Chrome; Video.js’s accent variable has narrower semantics. |
| `--media-secondary-color` | no direct equivalent | Add the skin source and author this palette role in your CSS. |
| `--media-control-background` | no direct equivalent | Add the skin source and author the CSS. |
| `--media-control-hover-background` | no direct equivalent | Add the skin source and author the CSS. |
| `--media-range-track-height` | no direct equivalent | Add the skin source and author the slider CSS. |
The packaged Video.js skins expose `--media-accent-color`, `--media-accent-text-color`, `--media-border-radius`, and `--media-scale-unit` for broad customization. Do not assume another Media Chrome variable will work because its name starts with `--media-`.
## Themes become skins
Media Chrome’s ``-based themes (`media-theme`) become Video.js [skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins) and [presets](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/presets). Start from a preset, then [add its skin source to your project](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source), rather than authoring a template.
React skins do not use Shadow DOM. Use `render` props when you build individual controls. Add the files for a ready-made skin when you need to change its control set or layout.
## Control the player imperatively
Control everything through the player’s store. Media Chrome had no player object; Video.js gives you one, with an action for every operation — `play`, `togglePaused`, `seek`, `setVolume`, `toggleFullscreen` — so one mental model covers playback and the state the browser doesn’t own, such as fullscreen, captions, and quality.
Select an action with the same [`usePlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/reference/api/use-player) hook you read state with:
```tsx
import { usePlayer } from '@videojs/react/video';
function FullscreenShortcut() {
const toggleFullscreen = usePlayer((state) => state.toggleFullscreen);
// Call toggleFullscreen() from your own UI.
return null;
}
```
The Media Chrome habit of scripting the media element directly still works, unchanged. The media is a plain child of the player, and Video.js derives player state from the native media events, so `video.play()` or `video.currentTime = 30` never leaves the controls out of sync. The media element also stays the way to swap `src`, replace the media component, and listen for native events.
Put a `ref` on the media component to reach the rendered `HTMLVideoElement`; there’s no `media` slot to reach through. For the Video.js media object, call `useMedia` from a component inside the player; media that wrap a playback engine expose it there through the `engine` escape hatch.
## Known gaps
These Media Chrome features have no direct equivalent yet. Several can be approximated; see [Workarounds](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-media-chrome#workarounds).
- No configurable `autohide` delay and no `autohideovercontrols` ([#1728](https://github.com/videojs/v10/issues/1728)). Disabling autohide (`autohide="-1"`) is covered by `visibility="always"` on the controls component; see [Workarounds](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-media-chrome#workarounds).
- No `defaultduration` placeholder before the media loads ([#1729](https://github.com/videojs/v10/issues/1729))
- Volume and muted preferences are not persisted across sessions, so Media Chrome’s `novolumepref` and `nomutedpref` opt-outs have nothing to opt out of ([#944](https://github.com/videojs/v10/issues/944)). Video.js can choose an initial subtitle track from the locale, but it does not yet remember the viewer’s later language choice ([#1786](https://github.com/videojs/v10/issues/1786)).
- No `breakpoints` or container-breakpoint attributes; use CSS container queries instead
- No `seektoliveoffset` or `noautoseektolive` controls, and live-edge offset and tolerance aren’t configurable ([#1730](https://github.com/videojs/v10/issues/1730))
- Chapters render and each time-slider segment reflects `data-active`, but there’s no player-level active chapter value, `chapterchange` event, or menu to jump between them ([#1873](https://github.com/videojs/v10/issues/1873))
- Cue points are not supported ([#1442](https://github.com/videojs/v10/issues/1442))
Chapters themselves do work. Add a default `` and the packaged skins segment the time slider and show the chapter title on hover, via `TimeSlider.Chapters` and `TimeSlider.ChapterTitle`.
## Workarounds
### Disable autohide (`autohide="-1"`)
Set `visibility="always"` on `Controls.Root` and the controls stay visible regardless of activity. Packaged skins don’t expose that prop; to keep a preset skin’s look, [add the skin source to your project](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source) and set it on the skin’s controls component rather than overriding private selectors.
### Breakpoints
The skin root is an inline-size container named `media-root`, so write responsive styles with container queries instead of `breakpoints` attributes. This is exactly how the built-in skins adapt:
```css
@container media-root (width > 40rem) {
.media-controls { /* wide layout */ }
}
```
### Default duration
There’s no player input for a pre-load duration. Use `preload="metadata"`, the default, so the real duration is known almost immediately; only `preload="none"` defers it. If you must defer loading, render your own static placeholder in markup.
### Preference persistence
Media Chrome remembers volume, muted state, and language across sessions. Video.js v10 persists nothing, so restore and save the values yourself.
```tsx
import { selectVolume, usePlayer } from '@videojs/react';
import { useEffect, useState } from 'react';
function PersistVolume() {
const volume = usePlayer(selectVolume);
const [readyToSave, setReadyToSave] = useState(false);
useEffect(() => {
const saved = localStorage.getItem('vjs:volume');
if (saved !== null) {
const savedVolume = Number(saved);
if (Number.isFinite(savedVolume)) volume.setVolume(savedVolume);
}
setReadyToSave(true);
}, []);
useEffect(() => {
if (!readyToSave) return;
localStorage.setItem('vjs:volume', String(volume.volume));
}, [readyToSave, volume.volume]);
return null;
}
```
### Live edge offsets
`seektoliveoffset` and `noautoseektolive` are governed by the playback engine rather than the UI layer, so there’s no attribute to tune them today. The escape hatch is a custom live control built against the `selectLive` and `selectTime` player state.
## See also
- [Installation](https://deploy-preview-2971--vjs10-site.netlify.app/docs/guides/installation/react)
- [UI components](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/ui-components)
- [Skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/skins) and [Customize skins](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins)