# Video.js v10 — React Guides (complete)

> Every React guides page in one file (about 116k tokens). Index with descriptions: https://videojs.org/docs/framework/react/guides/llms.txt

---

<!-- Source: https://videojs.org/docs/guides/installation/react -->

# 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.

> **Tip: Coming from another player?**
>
> Follow the migration guide for [Video.js 8](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8), [Mux Player](https://videojs.org/docs/framework/react/guides/migrate-from-mux-player), [Plyr](https://videojs.org/docs/framework/react/guides/migrate-from-plyr), [Media Chrome](https://videojs.org/docs/framework/react/guides/migrate-from-media-chrome), or [Vidstack](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack). 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: run `npx @videojs/cli agents skills` and follow the steps for the agent you are running in. If you can't run commands, follow the install instructions at https://github.com/videojs/skills instead. Then use the Video.js skill when you work on video or audio in this project. When installation details are needed, run `npx @videojs/cli agents init --framework react` to print the version-matched choices and instructions without changing files.
```

## Installation options for coding agents

The web Markdown page contains the default installation. Add the query parameters below to its `.md` URL for a complete, validated variation. From a project or an offline docs bundle, run the CLI command below instead. Both paths use the same installation renderer and only return instructions; they do not modify a project.

This page fixes the installation method to `packaged` and the framework to `react`.

```sh
npx @videojs/cli agents init
```

### Query parameters

- `project`: Whether to adapt the current project or scaffold a new one. New projects need a named app setup. Values: `new`, `existing`. Default: existing.
- `preset`: The player configuration and control set. Values: `video`, `audio`, `live-video`, `live-audio`, `background-video`. Default: video.
- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Values: `default`, `neutral`, `compat`, `none`. Default: default. Applies when preset is not background-video.
- `media`: The media source or playback adapter. See the preset compatibility map below. Values: `background-video`, `hls-background-video`, `cloudflare`, `dash`, `hls`, `html5-audio`, `html5-video`, `mux-audio`, `mux-background-video`, `mux-video`, `spotify`, `tiktok`, `twitch`, `vimeo`, `youtube`. Default: the selected preset's first compatible media source.
- `extensions`: A comma-separated list of optional player extensions compatible with the selected player. Pass `none` when no extension is needed. Values: `none`, `google-cast`, `mux-data`. Default: mux-data for Mux media; none otherwise (reported as defaulted).
- `source-url`: The http:// or https:// media URL placed in the generated player example. Pass `demo` to choose the Video.js demo source for the selected media explicitly. Default: the Video.js demo source for the selected media (reported as defaulted).
- `package-manager`: The command runner used for app setup, packages, Shadcn, and the development server. Values: `npm`, `pnpm`, `yarn`, `bun`. Default: pnpm. Applies when method is not cdn with template none.
- `template`: The app setup and file layout. Values: `next`, `vite`, `start`, `react-router`, `astro`, `laravel`. Default: next.

Run the command above without flags to see the corresponding CLI flags for every framework.

### Decide in this order

1. **Inspect the project.** Read package.json, framework config, and lockfiles to infer the framework, app setup, and package manager. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html.
2. **Choose the starting point.** Use existing when adapting a compatible project. Use new only when the user wants a new app or the intended workspace has no app. Confirm the choice when the workspace and request do not make it clear.
3. **Choose the player.** Use video unless the request signals another experience: audio, music, or podcasts use audio; a live stream uses live-video or live-audio; a muted, looping decorative video uses background-video. Ask only when those signals conflict.
4. **Choose the skin.** Use default unless the request asks for a minimal, cleaner, or more subtle look, which uses neutral; both contain the same controls. Use none only when the project builds its own controls. Ask only when those signals conflict.
5. **Choose the media.** Infer the adapter from the source when possible. Mux wins for Mux playback URLs: stream.mux.com/\<playback-id>.m3u8 or a bare playback ID uses mux-video, mux-audio, or mux-background-video rather than hls. Mux static renditions such as .mp4 or .m4a files use html5-video or html5-audio. Other .m3u8 URLs use hls.
6. **Choose extensions.** Mux Data is included by default for Mux video and audio sources. Add Google Cast when a standard or live video player with a ready-made skin should cast a compatible source. Use none when no extension is needed.
7. **Choose how to install.** This guide uses packaged modules, which need a bundler. Match the package manager to the project lockfile. For an existing HTML site without a build step, use CDN scripts instead.
8. **Return one explicit plan.** Confirm the choices once, then pass every applicable query parameter, including `extensions=none` when no extension is needed and `source-url=demo` when there is no media URL yet. Check that Defaulted options says none. Adapt conditional setup steps and existing paths before changing files.

### Compatible media sources by preset

- `video`: `html5-video`, `hls`, `dash`, `mux-video`, `vimeo`, `youtube`, `cloudflare`, `tiktok`, `twitch`
- `audio`: `html5-audio`, `mux-audio`, `spotify`
- `live-video`: `hls`, `mux-video`
- `live-audio`: `mux-audio`
- `background-video`: `background-video`, `hls-background-video`, `mux-background-video`

### App setup by framework

- `react`: templates `next`, `vite`, `start`, `react-router`, `astro`, `laravel`

### Installation pages

- [Packaged modules: React](https://videojs.org/docs/guides/installation/react.md)
- [Packaged modules: HTML](https://videojs.org/docs/guides/installation/html.md)
- [Packaged modules: Vue](https://videojs.org/docs/guides/installation/vue.md)
- [Packaged modules: Svelte](https://videojs.org/docs/guides/installation/svelte.md)
- [Editable Shadcn source: React source](https://videojs.org/docs/guides/installation/shadcn.md?framework=react)
- [Editable Shadcn source: HTML source](https://videojs.org/docs/guides/installation/shadcn.md?framework=html)
- [CDN: HTML from jsDelivr](https://videojs.org/docs/guides/installation/cdn.md)

If a preset and skin do not meet your user’s requirements, follow [Customize skins](https://videojs.org/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://videojs.org/docs/framework/react/llms.txt) to make sure you always have the latest information.

## Selected options

- `method`: `packaged`
- `framework`: `react`
- `project`: `existing`
- `preset`: `video`
- `skin`: `default`
- `media`: `html5-video`
- `extensions`: `none`
- `source-url`: `https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4`
- `package-manager`: `pnpm`
- `template`: `next`

Defaulted options: project, preset, skin, source-url, media, extensions, template, package-manager.

## Reproduce or change these instructions

```sh
npx @videojs/cli agents init --method packaged --framework react --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template next
```

## Install the packages

```bash
pnpm add @videojs/react@10.0.1
```

## Add your player

Merge the example into the existing Next.js route or component that should render the player, and preserve unrelated content.

### `app/page.tsx`

_Merge this into the existing file, or create the file when it is missing._

```tsx
import '@videojs/react/video/skin.css';
import { VideoPlayer, VideoSkin, Video } from '@videojs/react/video';

export default function Page() {
  return (
    <VideoPlayer>
      <VideoSkin style={{ width: '100%', aspectRatio: '16 / 9' }}>
        <Video src={"https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"} playsInline />
      </VideoSkin>
    </VideoPlayer>
  );
}
```

## Run your app

Start the development server and verify that the selected media plays.

_Long-running: start it in the background, verify the result, then stop it._

```bash
pnpm dev
```

> These are instructions only. Review and run the commands in your project; no files were modified.

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://videojs.org/docs/guides/installation/shadcn?framework=react#choose-how-to-install): Add editable skin source and build a working React or HTML player

## Choose what to do next

### Customize

- [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin): Change colors, typography, sizing, and poster presentation
- [UI components](https://videojs.org/docs/framework/react/guides/architecture#ui-components): Explore the building blocks used by skins and custom controls
- [Build your own component](https://videojs.org/docs/framework/react/guides/build-your-own-component): Connect custom UI to player state and actions

### Deploy

- [Browser support](https://videojs.org/docs/framework/react/guides/browser-support): Check supported browsers and rendering environments
- [TypeScript](https://videojs.org/docs/framework/react/guides/typescript): Configure TypeScript for Video.js packages
- [Bundlers](https://videojs.org/docs/framework/react/guides/bundlers): Check bundler compatibility
- [Content Security Policy](https://videojs.org/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://videojs.org/html5-video-support).

---

<!-- Source: https://videojs.org/docs/guides/installation/shadcn -->

# Shadcn Installation Guide

Add editable React or HTML skin source with the Shadcn registry

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.

> **Tip: Coming from another player?**
>
> Follow the React migration guide for [Video.js 8](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8), [Mux Player](https://videojs.org/docs/framework/react/guides/migrate-from-mux-player), [Plyr](https://videojs.org/docs/framework/react/guides/migrate-from-plyr), [Media Chrome](https://videojs.org/docs/framework/react/guides/migrate-from-media-chrome), or [Vidstack](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack). 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: run `npx @videojs/cli agents skills` and follow the steps for the agent you are running in. If you can't run commands, follow the install instructions at https://github.com/videojs/skills instead. Then use the Video.js skill when you work on video or audio in this project. When installation details are needed, run `npx @videojs/cli agents init --method shadcn --framework react` for React, or `npx @videojs/cli agents init --method shadcn --framework html` for plain HTML. The command prints version-matched choices and instructions without changing files.
```

## Installation options for coding agents

The web Markdown page contains the default installation. Add the query parameters below to its `.md` URL for a complete, validated variation. From a project or an offline docs bundle, run the CLI command below instead. Both paths use the same installation renderer and only return instructions; they do not modify a project.

This page fixes the installation method to `shadcn`. The `framework` query parameter selects React or HTML.

```sh
npx @videojs/cli agents init
```

### Query parameters

- `framework`: The application framework that will host the player. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html. Values: `react`, `html`. Default: react.
- `project`: Whether to adapt the current project or scaffold a new one. New projects need a named app setup. Values: `new`, `existing`. Default: existing.
- `preset`: The player configuration and control set. Values: `video`, `audio`, `live-video`, `live-audio`. Default: video.
- `skin`: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Values: `default`, `neutral`, `compat`. Default: default. Applies when preset is not background-video.
- `media`: The media source or playback adapter. See the preset compatibility map below. Values: `background-video`, `hls-background-video`, `cloudflare`, `dash`, `hls`, `html5-audio`, `html5-video`, `mux-audio`, `mux-background-video`, `mux-video`, `spotify`, `tiktok`, `twitch`, `vimeo`, `youtube`. Default: the selected preset's first compatible media source.
- `extensions`: A comma-separated list of optional player extensions compatible with the selected player. Pass `none` when no extension is needed. Values: `none`, `google-cast`, `mux-data`. Default: mux-data for Mux media; none otherwise (reported as defaulted).
- `source-url`: The http:// or https:// media URL placed in the generated player example. Pass `demo` to choose the Video.js demo source for the selected media explicitly. Default: the Video.js demo source for the selected media (reported as defaulted).
- `package-manager`: The command runner used for app setup, packages, Shadcn, and the development server. Values: `npm`, `pnpm`, `yarn`, `bun`. Default: pnpm. Applies when method is not cdn with template none.
- `template`: The app setup and file layout. Values: `next`, `vite`, `start`, `react-router`, `astro`, `laravel`. Default: next for React; vite otherwise.
- `styling`: The Shadcn source styling. Compatible values depend on the framework. Values: `tailwind`, `css`. Default: tailwind for React; css otherwise. Applies when method=shadcn.

Run the command above without flags to see the corresponding CLI flags for every framework.

### Decide in this order

1. **Inspect the project.** Read package.json, framework config, and lockfiles to infer the framework, app setup, and package manager. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html.
2. **Choose the starting point.** Use existing when adapting a compatible project. Use new only when the user wants a new app or the intended workspace has no app. Confirm the choice when the workspace and request do not make it clear.
3. **Choose the player.** Use video unless the request signals another experience: audio, music, or podcasts use audio; a live stream uses live-video or live-audio; a muted, looping decorative video uses background-video. Ask only when those signals conflict.
4. **Choose the skin.** Use default unless the request asks for a minimal, cleaner, or more subtle look, which uses neutral; both contain the same controls. Ask only when those signals conflict.
5. **Choose the media.** Infer the adapter from the source when possible. Mux wins for Mux playback URLs: stream.mux.com/\<playback-id>.m3u8 or a bare playback ID uses mux-video, mux-audio, or mux-background-video rather than hls. Mux static renditions such as .mp4 or .m4a files use html5-video or html5-audio. Other .m3u8 URLs use hls.
6. **Choose extensions.** Mux Data is included by default for Mux video and audio sources. Add Google Cast when a standard or live video player with a ready-made skin should cast a compatible source. Use none when no extension is needed.
7. **Choose how to install.** This guide uses Shadcn to copy editable skin source. React uses the React source catalog; plain HTML uses the HTML source catalog. Vue and Svelte use packaged modules.
8. **Choose the styling.** For React, use tailwind in a new app or an existing Tailwind app; otherwise use css. HTML source uses css.
9. **Return one explicit plan.** Confirm the choices once, then pass every applicable query parameter, including `extensions=none` when no extension is needed and `source-url=demo` when there is no media URL yet. Check that Defaulted options says none. Adapt conditional setup steps and existing paths before changing files.

### Compatible media sources by preset

- `video`: `html5-video`, `hls`, `dash`, `mux-video`, `vimeo`, `youtube`, `cloudflare`, `tiktok`, `twitch`
- `audio`: `html5-audio`, `mux-audio`, `spotify`
- `live-video`: `hls`, `mux-video`
- `live-audio`: `mux-audio`

### App setup and Shadcn styling by framework

- `react`: templates `next`, `vite`, `start`, `react-router`, `astro`, `laravel`; styling `tailwind`, `css`
- `html`: templates `vite`, `astro`, `laravel`; styling `css`

### Installation pages

- [Packaged modules: React](https://videojs.org/docs/guides/installation/react.md)
- [Packaged modules: HTML](https://videojs.org/docs/guides/installation/html.md)
- [Packaged modules: Vue](https://videojs.org/docs/guides/installation/vue.md)
- [Packaged modules: Svelte](https://videojs.org/docs/guides/installation/svelte.md)
- [Editable Shadcn source: React source](https://videojs.org/docs/guides/installation/shadcn.md?framework=react)
- [Editable Shadcn source: HTML source](https://videojs.org/docs/guides/installation/shadcn.md?framework=html)
- [CDN: HTML from jsDelivr](https://videojs.org/docs/guides/installation/cdn.md)

## Selected options

- `method`: `shadcn`
- `framework`: `react`
- `project`: `existing`
- `preset`: `video`
- `skin`: `default`
- `media`: `html5-video`
- `extensions`: `none`
- `source-url`: `https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4`
- `package-manager`: `pnpm`
- `template`: `next`
- `styling`: `tailwind`

Defaulted options: project, preset, skin, source-url, media, extensions, template, package-manager, styling.

## Reproduce or change these instructions

```sh
npx @videojs/cli agents init --method shadcn --framework react --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template next --styling tailwind
```

## Create components.json

_Only when components.json is missing._

The registry steps below need components.json, so create it when the project has none. `shadcn init` also rewrites the theme tokens in the global stylesheet, such as app/globals.css or src/index.css; review that diff and restore any project tokens that should stay.

```bash
pnpm dlx shadcn@latest init --base base --preset nova --yes
```

## Add the Video.js Registry

This adds the selected @videojs catalog when the namespace is missing. If components.json already defines @videojs with another URL, replace that value with the URL from this command first because Shadcn skips configured namespaces.

```bash
pnpm dlx shadcn@latest registry add @videojs=https://shadcn.videojs.org/r/react/{name}.json
```

## Add the skin source

Make sure the working tree is clean or checkpointed so every added or replaced file is reviewable; ask before committing. The add command overwrites an existing Video.js skin so catalog and theme changes fully apply. Review and remove obsolete Video.js style files left by a previous catalog.

```bash
pnpm dlx shadcn@latest add @videojs/video --overwrite --yes
```

## Add your player

Use the aliases.components value from components.json in the skin import when it differs from the generated @/components path. Merge the example into the existing Next.js route or component that should render the player, and preserve unrelated content.

### `app/page.tsx`

_Merge this into the existing file, or create the file when it is missing._

```tsx
import { VideoPlayer, Video } from '@videojs/react/video';
import { VideoSkin } from '@/components/videojs/video/skin';

export default function Page() {
  return (
    <VideoPlayer>
      <VideoSkin className="aspect-video w-full">
        <Video src={"https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"} playsInline />
      </VideoSkin>
    </VideoPlayer>
  );
}
```

## Run your app

Start the development server and verify that the selected media plays.

_Long-running: start it in the background, verify the result, then stop it._

```bash
pnpm dev
```

> These are instructions only. Review and run the commands in your project; no files were modified. Shadcn copies the current Video.js registry source, while package installs use the version shown above.

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 alias>/videojs/<preset>/skin.tsx`. Follow the [Customize skins](https://videojs.org/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://videojs.org/docs/framework/react/guides/customize-skins#style-skin-source): Change the installed layout, controls, styles, and interactions
- [UI components](https://videojs.org/docs/framework/react/guides/architecture#ui-components): Explore the building blocks used by skins and custom controls
- [Build your own component](https://videojs.org/docs/framework/react/guides/build-your-own-component): Connect custom UI to player state and actions

#### Deploy

- [Browser support](https://videojs.org/docs/framework/react/guides/browser-support): Check supported browsers and rendering environments
- [TypeScript](https://videojs.org/docs/framework/react/guides/typescript): Configure TypeScript for Video.js packages
- [Bundlers](https://videojs.org/docs/framework/react/guides/bundlers): Check bundler compatibility
- [Content Security Policy](https://videojs.org/docs/framework/react/guides/content-security-policy): Configure Content Security Policy for your player

---

<!-- Source: https://videojs.org/docs/framework/react/guides/build-your-own-component -->

# 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://videojs.org/docs/framework/react/guides/ui-components).
- **Restyle a control**: use CSS custom properties and data attributes. See [UI components](https://videojs.org/docs/framework/react/guides/ui-components).
- **Rearrange or remove controls**: add the skin source to your project, then modify it. See [Customize skins](https://videojs.org/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 [`<Player>`](https://videojs.org/docs/framework/react/reference/components/player) to access state. Place it inside [`<Container>`](https://videojs.org/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';

<Player>
  <Container>
    <VideoSkin>
      <Video src="video.mp4" />
    </VideoSkin>
    <SkipIntroButton />
  </Container>
</Player>
```

## 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 (
    <button
      className="skip-intro-button"
      onClick={() => 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
    </button>
  );
}
```

**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 [`<VideoPlayer>`](https://videojs.org/docs/framework/react/reference/components/player), to access state. Place it inside [`<Container>`](https://videojs.org/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 (
    <VideoPlayer>
      <Container>
        <VideoSkin>
          <Video src="video.mp4" />
        </VideoSkin>
        <SkipIntroButton />
      </Container>
    </VideoPlayer>
  );
}
```

## How it works

Custom components read player state and dispatch actions through [features](https://videojs.org/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://videojs.org/docs/framework/react/reference/api/feature-playback) |
| `currentTime`, `duration` | `seek()` | [Time](https://videojs.org/docs/framework/react/reference/api/feature-time) |
| `volume`, `muted` | `setVolume()`, `setMuted()` | [Volume](https://videojs.org/docs/framework/react/reference/api/feature-volume) |
| `isFullscreen` | `requestFullscreen()`, `exitFullscreen()` | [Fullscreen](https://videojs.org/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://videojs.org/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://videojs.org/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://videojs.org/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://videojs.org/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://videojs.org/docs/framework/react/guides/ui-components).

### Restyle a control

Use CSS custom properties and data attributes. See [UI components](https://videojs.org/docs/framework/react/guides/ui-components).

### Rearrange or remove controls

Add the skin source to your project and modify it. See [Customize skins](https://videojs.org/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 `<VideoPlayer>`), so `usePlayer` has no store to subscribe to.

## Related pages

### API

- [usePlayer](https://videojs.org/docs/framework/react/reference/api/use-player): Hook to access the player store from within a Player
- [createPlayer](https://videojs.org/docs/framework/react/reference/api/create-player): Factory function that creates a typed Player component and hooks
- [Container](https://videojs.org/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://videojs.org/docs/framework/react/guides/customize-skins): Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions

---

<!-- Source: https://videojs.org/docs/framework/react/guides/architecture -->

# 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://videojs.org/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 */}
<VideoPlayer>
  <VideoSkin>
    <Video src="video.mp4" />
  </VideoSkin>
</VideoPlayer>
```

You can access state and actions from anywhere within `VideoPlayer` with the [`usePlayer` hook](https://videojs.org/docs/framework/react/reference/api/use-player).

- [Learn more about state and actions](https://videojs.org/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
<VideoPlayer>
  <VideoSkin>
    <Video src="video.mp4" />
  </VideoSkin>
</VideoPlayer>
```

- [Learn more about skins](https://videojs.org/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
<VideoPlayer>
  <Container>
    <Video src="video.mp4" />
    <Controls.Root>
      <Controls.Content>
        <PlayButton />
        {/* ... */}
      </Controls.Content>
    </Controls.Root>
  </Container>
</VideoPlayer>
```

Skin source is a practical foundation for custom UI because it provides the same styled components as the packaged version. See [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-skin-source) to add it to your project.

- [Learn more about UI components](https://videojs.org/docs/framework/react/guides/ui-components)
- [Build your own component](https://videojs.org/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
<VideoPlayer>
  <VideoSkin>
    <HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" />
  </VideoSkin>
</VideoPlayer>
```

- [Learn more about media](https://videojs.org/docs/framework/react/guides/media-sources)

## Extensions

Extensions add behavior to a player without rendering UI or playing media themselves.

```tsx
<VideoPlayer>
  <VideoSkin>
    <MuxVideo source={{ playbackId: 'PLAYBACK_ID' }} />
    <MuxData />
    <GoogleCast />
  </VideoSkin>
</VideoPlayer>
```

An extension can provide behavior that a UI component controls: GoogleCast supplies the configurable Cast route, and [CastButton](https://videojs.org/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 `<video>` and `<audio>` tags.

Beyond the defaults, presets target more specific use cases. The `/background` preset combines a media component 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://videojs.org/docs/framework/react/guides/presets)

## Related pages

### Guides

- [Installation](https://videojs.org/docs/guides/installation/react): Install Video.js packages and build an accessible, customizable video player with composable controls
- [Features](https://videojs.org/docs/framework/react/guides/features): The state and actions each feature adds to the player
- [Skins](https://videojs.org/docs/framework/react/guides/skins): Packaged player designs that include both UI components and their styles.
- [Presets](https://videojs.org/docs/framework/react/guides/presets): Pre-packaged player configurations that bundle state management, skins, and media components for specific use cases.

---

<!-- Source: https://videojs.org/docs/framework/react/guides/customize-skins -->

# 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://videojs.org/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://videojs.org/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
<VideoSkin
  style={
    {
      '--media-accent-color': '#f5c518',
      '--media-border-radius': '1rem',
    } as React.CSSProperties
  }
>
  <Video src="video.mp4" />
</VideoSkin>
```

| Property name | What it changes | Value | Example |
| --- | --- | --- | --- |
| `--media-accent-color` | Slider fills, highlighted controls and menu items, and primary actions | [`<color>`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) | `#f5c518` |
| `--media-accent-text-color` | Text and icons shown on the accent color | [`<color>`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) | `black` |
| `--media-border-color` | The hairline around the player | [`<color>`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) | `transparent` |
| `--media-border-radius` | The player corner radius | A valid [border-radius value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/border-radius#values) | `1rem` |
| `--media-font-family` | The player interface font stack | A valid [font-family value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-family) | `Roboto, sans-serif` |
| `--media-object-fit` | How the media and poster fill the player | A valid [object-fit value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/object-fit) | `cover` |
| `--media-object-position` | Where the media and poster sit when they do not fill the player | A valid [object-position value](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/object-position) | `top` |
| `--media-scale-unit` | The base size for skin spacing, icons, and text | [`<length>`](https://developer.mozilla.org/en-US/docs/Web/CSS/length) | `1rem` |

If you omit `--media-accent-text-color`, the skins choose a contrasting text color from `--media-accent-color` using [`contrast-color()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/contrast-color). Browsers before Chrome 147, Firefox 146, and Safari 26 lack `contrast-color()` and use the theme’s default text color instead, which suits only the default accent, so set both properties together if you support those browsers.

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 component 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://videojs.org/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://videojs.org/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://videojs.org/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/<preset>`, 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://videojs.org/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/<preset>/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 Neutral, Compat, or one media preset | `components/videojs/styles/themes/neutral.css`, `components/videojs/styles/themes/compat.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://videojs.org/docs/framework/react/guides/skins). To create a control instead of editing one, follow [Build your own component](https://videojs.org/docs/framework/react/guides/build-your-own-component).

## Related pages

### Components

- [VideoSkin](https://videojs.org/docs/framework/react/reference/components/video-skin): The video preset's default skin with the modern, frosted look

### Guides

- [Skins](https://videojs.org/docs/framework/react/guides/skins): Packaged player designs that include both UI components and their styles.
- [Build your own UI component](https://videojs.org/docs/framework/react/guides/build-your-own-component): Create custom player controls that read state, dispatch actions, and stay accessible.

---

<!-- Source: https://videojs.org/docs/framework/react/guides/why-videojs -->

# 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 `<video>`?

The native `<video>` 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 `<video>` 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's default video controls](https://videojs.org/_astro/chrome-default-controls.D2ybhMTL.png)

Chrome

![Safari's default video controls](https://videojs.org/_astro/safari-default-controls.CPUt6ekS.png)

Safari

![Firefox's default video controls](https://videojs.org/_astro/firefox-default-controls.CYiJeU98.png)

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://videojs.org/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://videojs.org/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://videojs.org/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://videojs.org/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://videojs.org/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 (
    <VideoPlayer>
      <VideoSkin>
        <Video src="movie.mp4" />
      </VideoSkin>
    </VideoPlayer>
  );
}
```

**HTML**

```html
<script type="module">
  import '@videojs/html/video/player';
  import '@videojs/html/video/skin';
</script>

<video-player>
  <video-skin>
    <video src="movie.mp4"></video>
  </video-skin>
</video-player>
```

### 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://videojs.org/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://videojs.org/docs/framework/react/guides/build-with-ai)

## Related pages

### Guides

- [Installation](https://videojs.org/docs/guides/installation/react): Install Video.js packages and build an accessible, customizable video player with composable controls
- [Architecture](https://videojs.org/docs/framework/react/guides/architecture): How Video.js players are structured — state, UI, media, and extensions

---

<!-- Source: https://videojs.org/docs/framework/react/guides/browser-support -->

# Browser support

Browsers and rendering environments supported by Video.js 10, and how the packaged skins reach them

*Supported browsers and the versions of each that Video.js supports*

| Browser | Versions |
| --- | --- |
| Chrome | 111 and later |
| Edge | 111 and later |
| Firefox | 121 and later |
| Safari | 16.4 and later |
| Safari on iOS | 16.4 and later |

These versions account for 91.5% 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.

We test in and fix bugs for these versions. Each minimum comes from a feature with no fallback: `:has()` sets Firefox, [`color-mix()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix) and [`oklch()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch) set Chrome and Edge (Chrome 111, Firefox 113, Safari 16.2), and the JavaScript sets Safari, because it uses ES2022 syntax and [`adoptedStyleSheets`](https://developer.mozilla.org/en-US/docs/Web/API/Document/adoptedStyleSheets). Newer JavaScript APIs are feature-detected.

## CSS requirements

The packaged skins are generated CSS, and the build lowers them for the browsers above. It flattens CSS nesting, adds vendor prefixes such as `-webkit-backdrop-filter`, and writes each skin’s scope as a [`:where()`](https://developer.mozilla.org/en-US/docs/Web/CSS/:where) selector, which adds no specificity, rather than [`@scope`](https://developer.mozilla.org/en-US/docs/Web/CSS/@scope).

Skins you add as source through the [Shadcn registry](https://videojs.org/docs/guides/installation/shadcn?framework=react) keep `@scope`, which reads more clearly in files you edit. Their plain CSS versions need Chrome and Edge 118, Firefox 146, and Safari and iOS 17.4 unless you [flatten `@scope` in your build](https://videojs.org/docs/framework/react/guides/browser-support#flatten-scope-in-registry-skins); the Tailwind versions style elements with utility classes and follow the versions above.

Newer color functions get a fallback, and the original declaration moves inside [`@supports`](https://developer.mozilla.org/en-US/docs/Web/CSS/@supports), so browsers that have the function still use it:

- [`light-dark()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark) uses its light color. The audio skins render their light theme, and the video skins keep the light hairline border.
- [`contrast-color()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/contrast-color) uses each theme’s default text color on primary buttons and the inherited text color elsewhere. The fallback cannot read a custom accent, so set `--media-accent-text-color` whenever you set `--media-accent-color`; see [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins).
- [Relative colors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_colors/Relative_colors) that keep their origin’s channels, which build the scrims behind the controls, become `color-mix()`. Subtle shadows derived from `currentColor` have no equivalent and are left out.

Tooltips, menus, and popovers use the [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) where it exists (Chrome 114, Firefox 125, Safari 17). In older supported versions they stay inside the player instead of the top layer: the skins hide them while closed and position them against the player while open, so on the video skins a menu taller than the player is cut off.

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/). **Required** features have no fallback. **Degrades** features lose one visual detail. **Has a fallback** features keep working another way: anchor positioning falls back to positions computed in JavaScript, `:dir()` sits beside `[dir="rtl"]` selectors, and the packaged skins flatten `@scope` into `:where()` selectors.

*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.*

| Feature | Chrome and Edge | Firefox | Safari and iOS | Global support |
| --- | --- | --- | --- | --- |
| [`@scope`](https://caniuse.com/css-cascade-scope) Has a fallback. Packaged skins use :where() selectors instead; registry CSS skins need it. | 118 | 146 | 17.4 | 90.0% |
| [`@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) Has a fallback. Right-to-left layout follows the dir attribute instead. | 120 | 17 | 16.4 | 91.4% |
| [`Relative color syntax`](https://caniuse.com/css-relative-colors) Degrades. Control scrims fall back to color-mix(), and subtle 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% |

Older browsers than the baseline are not tested. Without `:has()`, `@container`, `@layer`, `color-mix()`, or `oklch()`, the skins lose focus states, layout, or colors.

## Build the skin CSS yourself

Skins are stylesheets you import, such as `@videojs/react/video/skin.css`, so your bundler’s CSS pipeline processes them.

[Lightning CSS](https://lightningcss.dev/transpilation.html), which Vite uses to minify CSS, rewrites `light-dark()` and `:dir()` for every browser when its targets include older ones, not only for those older browsers. Its `light-dark()` output depends on a `color-scheme` declaration the skins do not make, so the skin colors break. The skins keep `light-dark()` inside `@supports` checks, which Lightning CSS 1.32 and earlier leave alone but 1.33 and later rewrite anyway. The skins already handle both features, so exclude them:

**vite.config.ts**

```ts
import { Features } from 'lightningcss';
import { defineConfig } from 'vite';

export default defineConfig({
  css: {
    lightningcss: { exclude: Features.LightDark | Features.DirSelector },
  },
});
```

### Flatten `@scope` in registry skins

Registry skins in plain CSS keep `@scope`, and Lightning CSS passes it through unchanged. To reach browsers without `@scope`, add a PostCSS plugin that rewrites each block into descendant selectors prefixed with [`:where(root)`](https://developer.mozilla.org/en-US/docs/Web/CSS/:where), which adds no specificity. Vite, Next.js, and most bundlers pick it up from `postcss.config.mjs` and run it before Lightning CSS:

```bash
npm install --save-dev postcss postcss-selector-parser
```

**postcss.config.mjs**

```js
import selectorParser from 'postcss-selector-parser';

/** Rewrite `@scope (<root>) { … }` 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: `:where(${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()] };
```

Flattening trades scope proximity for source order, the same way the packaged skins do. Keep the Lightning CSS `exclude` setting above so the colors still work.

## 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://videojs.org/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://videojs.org/docs/guides/installation/react): Install Video.js packages and build an accessible, customizable video player with composable controls
- [Bundlers](https://videojs.org/docs/framework/react/guides/bundlers): Bundler requirements for Video.js package exports, CSS, and wrapper libraries

---

<!-- Source: https://videojs.org/docs/framework/react/guides/build-with-ai -->

# 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: run `npx @videojs/cli agents skills` and follow the steps for the agent you are running in. If you can't run commands, follow the install instructions at https://github.com/videojs/skills instead. Then use the Video.js skill when you work on video or audio in this project. When installation details are needed, run `npx @videojs/cli agents init --framework react` to print the version-matched choices and instructions without changing files.
```

## 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

Follow the steps for your coding agent. To print the same steps in a terminal, run:

**Terminal**

```sh
npx @videojs/cli agents skills
```

Add `--agent claude-code,cursor` to print only those agents. `--scope project` or `--scope local` changes the Claude Code installation scope from its `user` default, and `--global` adds `-g` to the `skills` installer command. Like `agents init`, the command only prints instructions.

#### 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
```

Start a new VS Code session after installation, or reload the window.

#### Cursor

Open **Customize**, select **Plugins**, choose **From GitHub Repository**, and enter:

```text
https://github.com/videojs/skills
```

Start a new Cursor session after installation, or reload the window.

#### Other coding agents

Use the open `skills` installer and select your agent when prompted:

**Terminal**

```sh
npx skills add https://github.com/videojs/skills
```

Start a new session in your coding agent after installation.

Project-local installation is the default. Add `-g` if you want the skill available in every project.

To skip the prompts, name the agent and confirm up front, for example `npx skills add https://github.com/videojs/skills --agent <agent> --yes`.

### 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 skills find docs

The skill uses documentation in this order:

1. **Version-matched installation instructions.** `npx @videojs/cli agents init` lists valid choices for every framework. Adding flags prints one complete installation plan. When the project already has a different `@videojs/react` or `@videojs/html` version, the plan names the pinned command for that release. The command only returns instructions; it does not prompt, install packages, or write files.
2. **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.
3. **Live docs.** If commands cannot run, the skill reads the relevant [React](https://videojs.org/docs/framework/react/llms.txt) or [HTML](https://videojs.org/docs/framework/html/llms.txt) documentation index, then follows it to the matching installation guide.
4. **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.

The old `npx @videojs/cli docs` workflow was removed. `@videojs/cli` now contains only `agents init` and `agents skills`, in a single file with no dependencies, so running it does not download the player packages.

### 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://videojs.org/docs/guides/installation/react): Install Video.js packages and build an accessible, customizable video player with composable controls
- [Architecture](https://videojs.org/docs/framework/react/guides/architecture): How Video.js players are structured — state, UI, media, and extensions
- [Build your own UI component](https://videojs.org/docs/framework/react/guides/build-your-own-component): Create custom player controls that read state, dispatch actions, and stay accessible.

---

<!-- Source: https://videojs.org/docs/framework/react/guides/v10-roadmap -->

# v10 Roadmap

Where Video.js v10 stands, what comes after 10.0, and the support plan for Video.js 8

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 10

- Stable and recommended for new projects. Start with the [installation guide](https://videojs.org/docs/guides/installation/react)
- Follows semantic versioning: breaking changes wait for a new major version
- Covers the fundamentals of Video.js 8
- Migration guides for [Video.js 8](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8), [Mux Player](https://videojs.org/docs/framework/react/guides/migrate-from-mux-player), [Plyr](https://videojs.org/docs/framework/react/guides/migrate-from-plyr), [Media Chrome](https://videojs.org/docs/framework/react/guides/migrate-from-media-chrome), and [Vidstack](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack), each listing its known gaps

### 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

## After 10.0

These land in 10.x minor releases as they’re ready.

### Feature parity with Video.js 8 contrib

- Ads integration
- Analytics support
- Plugin ecosystem migration, dependent on community contributions

### Engine development focus

- Lightweight adaptive streaming
- MoQ (Media over QUIC) support

## Support plan for Video.js 8

- Documentation stays at [legacy.videojs.org](https://legacy.videojs.org)
- Hosted CDN copies remain available
- From 2027, security patches only, and community contributions are de-prioritized

---

**Want to contribute?** Check out the [v10 repository on GitHub](https://github.com/videojs/v10) to get involved.

## Related pages

### Guides

- [Why Video.js?](https://videojs.org/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://videojs.org/docs/guides/installation/react): Install Video.js packages and build an accessible, customizable video player with composable controls

---

<!-- Source: https://videojs.org/docs/framework/react/guides/typescript -->

# 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://videojs.org/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://videojs.org/docs/guides/installation/react): Install Video.js packages and build an accessible, customizable video player with composable controls
- [Bundlers](https://videojs.org/docs/framework/react/guides/bundlers): Bundler requirements for Video.js package exports, CSS, and wrapper libraries

---

<!-- Source: https://videojs.org/docs/framework/react/guides/bundlers -->

# 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://videojs.org/docs/guides/installation/react): Install Video.js packages and build an accessible, customizable video player with composable controls
- [TypeScript](https://videojs.org/docs/framework/react/guides/typescript): TypeScript version and module resolution requirements for Video.js packages

---

<!-- Source: https://videojs.org/docs/framework/react/guides/content-security-policy -->

# 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 manifests, playlists, captions, and segment requests when using HLS or DASH playback.
- `media-src blob:` is required when your engine uses Media Source Extensions (MSE), including HLS and DASH engines.
- `worker-src blob:` is required for hls.js workers, which are enabled by default.
- `style-src 'unsafe-inline'` is required for some player UI.

## Recommended policy

Start with this policy for native, HLS, and DASH playback. For embeds and Google Cast, add the provider origins below.

```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:;
  frame-src 'none';
```

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`. Add it to `style-src` too if you load stylesheets from that CDN.

Replace broad sources such as `https:` with the exact origins your player uses. Remove sources your deployment does not need. Keep `media-src blob:` for engines that use MSE. Keep `worker-src blob:` for engines that create blob workers, as hls.js does by default.

## Allow embeds and Google Cast

Add only the origins for the providers you use. Extend `script-src` with their script origins. If a provider lists iframe origins, replace `frame-src 'none'` with those origins. A dash means the Video.js integration does not directly load that resource.

| Provider | `script-src` origins | `frame-src` origins |
| --- | --- | --- |
| YouTube | `https://www.youtube.com` | `https://www.youtube.com` or `https://www.youtube-nocookie.com`, depending on your source URL |
| Vimeo | — | `https://player.vimeo.com`; `https://vimeo.com` for live events |
| Spotify | `https://open.spotify.com` | `https://open.spotify.com` |
| TikTok | — | `https://www.tiktok.com` |
| Twitch | — | `https://player.twitch.tv` |
| Cloudflare | `https://embed.videodelivery.net` | `https://iframe.videodelivery.net` or your `https://customer-<code>.cloudflarestream.com` origin |
| Google Cast | `https://www.gstatic.com` | — |
| Wistia | `https://fast.wistia.com` and `https://fast.wistia.net` | `https://fast.wistia.com` and `https://fast.wistia.net` if the SDK falls back to an iframe |

For Cloudflare, use `https://iframe.videodelivery.net` unless your source URL names a customer origin. In that case, replace `<code>` with your customer code.

The Wistia SDK bundled with Video.js normally renders its player in the page and can fall back to an iframe. It loads scripts and media data from `fast.wistia.com` and `fast.wistia.net`. If you narrow `connect-src`, keep both origins.

The table covers entry scripts and embed frames. Provider SDKs can request additional resources. Test your selected media under your policy, check the browser’s CSP violations, and allow the exact origins those requests need.

## Related pages

### Guides

- [Installation](https://videojs.org/docs/guides/installation/react): Install Video.js packages and build an accessible, customizable video player with composable controls

---

<!-- Source: https://videojs.org/docs/framework/react/guides/features -->

# 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.

- [See every feature’s state and actions](https://videojs.org/docs/framework/react/reference/api/player-store)

## 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';

<VideoPlayer>
  <VideoSkin>
    <Video src="movie.mp4" />
  </VideoSkin>
</VideoPlayer>
```

Feature bundles are usually paired with specific skins and media components 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://videojs.org/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://videojs.org/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://videojs.org/docs/framework/react/reference/api/feature-playback), [`selectVolume`](https://videojs.org/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://videojs.org/docs/framework/react/reference/components/mute-button), [`PiPButton`](https://videojs.org/docs/framework/react/reference/components/pip-button), and [`FullscreenButton`](https://videojs.org/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.pictureInPictureAvailability);

  if (availability !== 'available') return null;

  return <PiPButton />;
}
```

---

<!-- Source: https://videojs.org/docs/framework/react/guides/skins -->

# 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.

The video, audio, live video, and live audio presets each provide Default, Neutral, and Compat skins. Compat uses plain surfaces and basic controls, with broader browser compatibility as its design goal.

## 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 (
    <VideoPlayer>
      <VideoSkin>
        <Video src="video.mp4" />
      </VideoSkin>
    </VideoPlayer>
  );
}
```

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://videojs.org/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://videojs.org/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://videojs.org/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://videojs.org/docs/framework/react/guides/build-your-own-component)

## Skins, features, and presets

Each skin is built with specific [features](https://videojs.org/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://videojs.org/docs/framework/react/reference/api/feature-playback), [playbackRate](https://videojs.org/docs/framework/react/reference/api/feature-playback-rate), [quality](https://videojs.org/docs/framework/react/reference/api/feature-quality), [audioTrack](https://videojs.org/docs/framework/react/reference/api/feature-audio-track), [volume](https://videojs.org/docs/framework/react/reference/api/feature-volume), [time](https://videojs.org/docs/framework/react/reference/api/feature-time), [source](https://videojs.org/docs/framework/react/reference/api/feature-source), [buffer](https://videojs.org/docs/framework/react/reference/api/feature-buffer), [fullscreen](https://videojs.org/docs/framework/react/reference/api/feature-fullscreen), [pip](https://videojs.org/docs/framework/react/reference/api/feature-pip), [remotePlayback](https://videojs.org/docs/framework/react/reference/api/feature-remote-playback), [controls](https://videojs.org/docs/framework/react/reference/api/feature-controls), [textTrack](https://videojs.org/docs/framework/react/reference/api/feature-text-tracks), [error](https://videojs.org/docs/framework/react/reference/api/feature-error), [metadata](https://videojs.org/docs/framework/react/reference/api/feature-metadata); **Skins:** `<CompatVideoSkin>` with `import '@videojs/react/video/compat-skin.css';`, `<NeutralVideoSkin>` with `import '@videojs/react/video/neutral-skin.css';`, `<VideoSkin>` with `import '@videojs/react/video/skin.css';`; **Default media component:** `<Video>` |
| `@videojs/react/audio` | Audio-only player preset with playback and volume controls. | **Feature bundle:** `audioFeatures`; **Features:** [playback](https://videojs.org/docs/framework/react/reference/api/feature-playback), [playbackRate](https://videojs.org/docs/framework/react/reference/api/feature-playback-rate), [volume](https://videojs.org/docs/framework/react/reference/api/feature-volume), [time](https://videojs.org/docs/framework/react/reference/api/feature-time), [source](https://videojs.org/docs/framework/react/reference/api/feature-source), [buffer](https://videojs.org/docs/framework/react/reference/api/feature-buffer), [error](https://videojs.org/docs/framework/react/reference/api/feature-error), [metadata](https://videojs.org/docs/framework/react/reference/api/feature-metadata); **Skins:** `<CompatAudioSkin>` with `import '@videojs/react/audio/compat-skin.css';`, `<NeutralAudioSkin>` with `import '@videojs/react/audio/neutral-skin.css';`, `<AudioSkin>` with `import '@videojs/react/audio/skin.css';`; **Default media component:** `<Audio>` |
| `@videojs/react/background` | Ambient background video preset with no user controls. | **Feature bundle:** `backgroundFeatures`; **Features:** –; **Skins:** `<BackgroundVideoSkin>` with `import '@videojs/react/background/skin.css';`; **Default media component:** `<BackgroundVideo>` |
| `@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://videojs.org/docs/framework/react/reference/api/feature-playback), [volume](https://videojs.org/docs/framework/react/reference/api/feature-volume), [time](https://videojs.org/docs/framework/react/reference/api/feature-time), [source](https://videojs.org/docs/framework/react/reference/api/feature-source), [buffer](https://videojs.org/docs/framework/react/reference/api/feature-buffer), [error](https://videojs.org/docs/framework/react/reference/api/feature-error), [live](https://videojs.org/docs/framework/react/reference/api/feature-live), [metadata](https://videojs.org/docs/framework/react/reference/api/feature-metadata); **Skins:** `<CompatLiveAudioSkin>` with `import '@videojs/react/live-audio/compat-skin.css';`, `<NeutralLiveAudioSkin>` with `import '@videojs/react/live-audio/neutral-skin.css';`, `<LiveAudioSkin>` with `import '@videojs/react/live-audio/skin.css';`; **Default media component:** `<Audio>` |
| `@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://videojs.org/docs/framework/react/reference/api/feature-playback), [volume](https://videojs.org/docs/framework/react/reference/api/feature-volume), [time](https://videojs.org/docs/framework/react/reference/api/feature-time), [source](https://videojs.org/docs/framework/react/reference/api/feature-source), [buffer](https://videojs.org/docs/framework/react/reference/api/feature-buffer), [fullscreen](https://videojs.org/docs/framework/react/reference/api/feature-fullscreen), [pip](https://videojs.org/docs/framework/react/reference/api/feature-pip), [remotePlayback](https://videojs.org/docs/framework/react/reference/api/feature-remote-playback), [controls](https://videojs.org/docs/framework/react/reference/api/feature-controls), [textTrack](https://videojs.org/docs/framework/react/reference/api/feature-text-tracks), [error](https://videojs.org/docs/framework/react/reference/api/feature-error), [live](https://videojs.org/docs/framework/react/reference/api/feature-live), [metadata](https://videojs.org/docs/framework/react/reference/api/feature-metadata); **Skins:** `<CompatLiveVideoSkin>` with `import '@videojs/react/live-video/compat-skin.css';`, `<NeutralLiveVideoSkin>` with `import '@videojs/react/live-video/neutral-skin.css';`, `<LiveVideoSkin>` with `import '@videojs/react/live-video/skin.css';`; **Default media component:** `<Video>` |

- [Read about presets](https://videojs.org/docs/framework/react/guides/presets)

---

<!-- Source: https://videojs.org/docs/framework/react/guides/presets -->

# Presets

Pre-packaged player configurations that bundle state management, skins, and media components for specific use cases.

A **preset** packages what you need for a specific player use case. It can include special [state management](https://videojs.org/docs/framework/react/guides/features), one or more [skins](https://videojs.org/docs/framework/react/guides/skins) for UI, and specific media components. 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 component 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 (
    <BackgroundVideoPlayer>
      <BackgroundVideoSkin>
        <BackgroundVideo src="hero.mp4" />
      </BackgroundVideoSkin>
    </BackgroundVideoPlayer>
  );
}
```

## Available presets

The default presets are `/video` and `/audio`. These cover the baseline controls you’d expect from the HTML `<video>` and `<audio>` 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.

The video, audio, live video, and live audio presets also export Compat skins. For example, React exports `CompatVideoSkin` with `@videojs/react/video/compat-skin.css`; HTML registers `<video-compat-skin>` through `@videojs/html/video/compat-skin`.

| Import | Description | Details |
| --- | --- | --- |
| `@videojs/react/video` | General-purpose video player preset with full playback controls. | **Feature bundle:** `videoFeatures`; **Features:** [playback](https://videojs.org/docs/framework/react/reference/api/feature-playback), [playbackRate](https://videojs.org/docs/framework/react/reference/api/feature-playback-rate), [quality](https://videojs.org/docs/framework/react/reference/api/feature-quality), [audioTrack](https://videojs.org/docs/framework/react/reference/api/feature-audio-track), [volume](https://videojs.org/docs/framework/react/reference/api/feature-volume), [time](https://videojs.org/docs/framework/react/reference/api/feature-time), [source](https://videojs.org/docs/framework/react/reference/api/feature-source), [buffer](https://videojs.org/docs/framework/react/reference/api/feature-buffer), [fullscreen](https://videojs.org/docs/framework/react/reference/api/feature-fullscreen), [pip](https://videojs.org/docs/framework/react/reference/api/feature-pip), [remotePlayback](https://videojs.org/docs/framework/react/reference/api/feature-remote-playback), [controls](https://videojs.org/docs/framework/react/reference/api/feature-controls), [textTrack](https://videojs.org/docs/framework/react/reference/api/feature-text-tracks), [error](https://videojs.org/docs/framework/react/reference/api/feature-error), [metadata](https://videojs.org/docs/framework/react/reference/api/feature-metadata); **Skins:** `<CompatVideoSkin>` with `import '@videojs/react/video/compat-skin.css';`, `<NeutralVideoSkin>` with `import '@videojs/react/video/neutral-skin.css';`, `<VideoSkin>` with `import '@videojs/react/video/skin.css';`; **Default media component:** `<Video>` |
| `@videojs/react/audio` | Audio-only player preset with playback and volume controls. | **Feature bundle:** `audioFeatures`; **Features:** [playback](https://videojs.org/docs/framework/react/reference/api/feature-playback), [playbackRate](https://videojs.org/docs/framework/react/reference/api/feature-playback-rate), [volume](https://videojs.org/docs/framework/react/reference/api/feature-volume), [time](https://videojs.org/docs/framework/react/reference/api/feature-time), [source](https://videojs.org/docs/framework/react/reference/api/feature-source), [buffer](https://videojs.org/docs/framework/react/reference/api/feature-buffer), [error](https://videojs.org/docs/framework/react/reference/api/feature-error), [metadata](https://videojs.org/docs/framework/react/reference/api/feature-metadata); **Skins:** `<CompatAudioSkin>` with `import '@videojs/react/audio/compat-skin.css';`, `<NeutralAudioSkin>` with `import '@videojs/react/audio/neutral-skin.css';`, `<AudioSkin>` with `import '@videojs/react/audio/skin.css';`; **Default media component:** `<Audio>` |
| `@videojs/react/background` | Ambient background video preset with no user controls. | **Feature bundle:** `backgroundFeatures`; **Features:** –; **Skins:** `<BackgroundVideoSkin>` with `import '@videojs/react/background/skin.css';`; **Default media component:** `<BackgroundVideo>` |
| `@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://videojs.org/docs/framework/react/reference/api/feature-playback), [volume](https://videojs.org/docs/framework/react/reference/api/feature-volume), [time](https://videojs.org/docs/framework/react/reference/api/feature-time), [source](https://videojs.org/docs/framework/react/reference/api/feature-source), [buffer](https://videojs.org/docs/framework/react/reference/api/feature-buffer), [error](https://videojs.org/docs/framework/react/reference/api/feature-error), [live](https://videojs.org/docs/framework/react/reference/api/feature-live), [metadata](https://videojs.org/docs/framework/react/reference/api/feature-metadata); **Skins:** `<CompatLiveAudioSkin>` with `import '@videojs/react/live-audio/compat-skin.css';`, `<NeutralLiveAudioSkin>` with `import '@videojs/react/live-audio/neutral-skin.css';`, `<LiveAudioSkin>` with `import '@videojs/react/live-audio/skin.css';`; **Default media component:** `<Audio>` |
| `@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://videojs.org/docs/framework/react/reference/api/feature-playback), [volume](https://videojs.org/docs/framework/react/reference/api/feature-volume), [time](https://videojs.org/docs/framework/react/reference/api/feature-time), [source](https://videojs.org/docs/framework/react/reference/api/feature-source), [buffer](https://videojs.org/docs/framework/react/reference/api/feature-buffer), [fullscreen](https://videojs.org/docs/framework/react/reference/api/feature-fullscreen), [pip](https://videojs.org/docs/framework/react/reference/api/feature-pip), [remotePlayback](https://videojs.org/docs/framework/react/reference/api/feature-remote-playback), [controls](https://videojs.org/docs/framework/react/reference/api/feature-controls), [textTrack](https://videojs.org/docs/framework/react/reference/api/feature-text-tracks), [error](https://videojs.org/docs/framework/react/reference/api/feature-error), [live](https://videojs.org/docs/framework/react/reference/api/feature-live), [metadata](https://videojs.org/docs/framework/react/reference/api/feature-metadata); **Skins:** `<CompatLiveVideoSkin>` with `import '@videojs/react/live-video/compat-skin.css';`, `<NeutralLiveVideoSkin>` with `import '@videojs/react/live-video/neutral-skin.css';`, `<LiveVideoSkin>` with `import '@videojs/react/live-video/skin.css';`; **Default media component:** `<Video>` |

Each preset has a reference page that lists its player, feature bundle, skins, media, and exports:

- [Video preset](https://videojs.org/docs/framework/react/reference/api/preset-video)
- [Audio preset](https://videojs.org/docs/framework/react/reference/api/preset-audio)
- [Live video preset](https://videojs.org/docs/framework/react/reference/api/preset-live-video)
- [Live audio preset](https://videojs.org/docs/framework/react/reference/api/preset-live-audio)
- [Background preset](https://videojs.org/docs/framework/react/reference/api/preset-background)

## 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 component:

- **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://videojs.org/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 component** — One 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 components 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 component.

### 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 (
    <Player>
      <Container>
        <BackgroundVideo src="hero.mp4" />
        <PlayButton />
      </Container>
    </Player>
  );
}
```

### Skin source

If a preset’s skin is close but not quite right, [add its source to your project](https://videojs.org/docs/framework/react/guides/customize-skins#style-skin-source) and customize its components and styles.

### Swap the media component

A preset’s default media component 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
<VideoPlayer>
  <VideoSkin>
    <HlsJsVideo src="https://example.com/stream.m3u8" />
  </VideoSkin>
</VideoPlayer>
```

---

<!-- Source: https://videojs.org/docs/framework/react/guides/ui-components -->

# 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 [`<Player>`](https://videojs.org/docs/framework/react/reference/components/player).

However, you should consider placing your components in `<Container>`. Components in `<Container>` will go fullscreen with the player, respond to user activity, and more.

- [Read more about `<Container>`](https://videojs.org/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';

<PlayButton
  render={(props, state) => (
    <button {...props}>
      {state.paused ? <PlayIcon /> : <PauseIcon />}
    </button>
  )}
/>
```

`className` and `style` also accept functions of state for dynamic styling without a full render prop:

```tsx
<PlayButton
  className={(state) =>
    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
<VolumeSlider.Root orientation="vertical">
  <VolumeSlider.Track>
    <VolumeSlider.Fill />
  </VolumeSlider.Track>
  <VolumeSlider.Thumb />
</VolumeSlider.Root>
```

---

<!-- Source: https://videojs.org/docs/framework/react/guides/accessibility -->

# 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://videojs.org/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://videojs.org/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://videojs.org/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://videojs.org/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://videojs.org/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://videojs.org/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://videojs.org/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://videojs.org/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://videojs.org/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://videojs.org/docs/framework/react/guides/background-video) and [Autoplay](https://videojs.org/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.

---

<!-- Source: https://videojs.org/docs/framework/react/guides/media-sources -->

# Media sources

Set what a media component plays and how its engine plays it with the structured source property

Every media component 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
<HlsJsVideo
  source={{
    src: 'https://example.com/stream.m3u8',
    preferPlayback: 'mse',
    engine: { hlsJs: { maxBufferLength: 60 } },
  }}
/>
```

## Where source options belong

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://videojs.org/docs/framework/react/guides/mux-data), [GoogleCast](https://videojs.org/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
<HlsJsVideo source={{ src: 'https://example.com/asset?id=42', type: 'application/vnd.apple.mpegurl' }} />
```

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
<HlsJsVideo source={{ src: 'https://example.com/a.m3u8', preferPlayback: 'native' }} />
```

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
<HlsJsVideo source={{ src, type: 'video/mp4', preferPlayback: 'native' }} />

// later: type and preferPlayback are gone, because the new object omits them
<HlsJsVideo source={{ src }} />
```

## 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.
<HlsJsVideo source={{ src, engine: { hlsJs: { maxBufferLength: 60 } } }} />
```

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.

The hls.js adapter recreates its playback engine when `source.engine`, `source.drm`, `source.preferPlayback`, or the resolved content type changes. A new URL with the same resolved type reuses the engine when those options are unchanged. dash.js and Shaka apply changes to their engine settings in place.

## 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://videojs.org/docs/framework/react/reference/components/hlsjs-video), [MuxVideo](https://videojs.org/docs/framework/react/reference/components/mux-video), [MuxAudio](https://videojs.org/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://videojs.org/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://videojs.org/docs/framework/react/guides/media-sources#licensing-one-engine-differently)) |
| `engine.dashJs` | [DashVideo](https://videojs.org/docs/framework/react/reference/components/dash-video) | [dash.js settings](https://cdn.dashjs.org/latest/jsdoc/module-Settings.html) |
| `engine.shaka` | [ShakaVideo](https://videojs.org/docs/framework/react/reference/components/shaka-video) | a [Shaka Player configuration](https://shaka-project.github.io/shaka-player/docs/api/shaka.extern.html#.PlayerConfiguration) |
| `engine.vimeo` | [VimeoVideo](https://videojs.org/docs/framework/react/reference/components/vimeo-video) | [Vimeo embed parameters](https://developer.vimeo.com/player/sdk/embed) |
| `engine.youtube` | [YouTubeVideo](https://videojs.org/docs/framework/react/reference/components/youtube-video) | [YouTube player parameters](https://developer.chrome.com/docs/youtube/iframe_api_reference#Parameters) |
| `engine.cloudflare` | [CloudflareVideo](https://videojs.org/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://videojs.org/docs/framework/react/reference/components/spotify-audio) | [Spotify embed options](https://developer.spotify.com/documentation/embeds) |
| `engine.tiktok` | [TikTokVideo](https://videojs.org/docs/framework/react/reference/components/tiktok-video) | [TikTok player parameters](https://developers.tiktok.com/doc/embed-player) |
| `engine.twitch` | [TwitchVideo](https://videojs.org/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
<HlsJsVideo
  source={{
    src: 'https://example.com/stream.m3u8',
    engine: { hlsJs: { maxBufferLength: 60, enableWorker: false } },
  }}
/>
```

dash.js applies `engine.dashJs` settings to the running player:

```tsx
<DashVideo
  source={{
    src: 'https://example.com/manifest.mpd',
    engine: { dashJs: { streaming: { abr: { maxBitrate: { video: 2000 } } } } },
  }}
/>
```

Because `engine.dashJs` replaces rather than merges, dropping a key restores the dash.js default instead of leaving the old value behind.

Shaka also applies `engine.shaka` configuration to the running player without recreating it. Dropping a key restores its default. Video.js enables `abr.restrictToElementSize` by default to limit adaptation to the player size.

### 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
<HlsJsVideo source={{ src: 'https://example.com/stream.m3u8', preferPlayback: 'native' }} />
```

It’s a preference, not a demand — Video.js falls back to whichever path can actually play the source. `HlsJsVideo`, `MuxVideo`, and `MuxAudio` accept it; DASH and Vimeo have no second playback path.

`maxAutoResolution` caps the highest rendition adaptive bitrate selection reaches for on its own:

```tsx
<HlsJsVideo source={{ src: 'https://example.com/stream.m3u8', maxAutoResolution: '720p' }} />
```

The cap limits automatic selection without hiding anything. Renditions above it stay in `videoRenditions`, so a viewer can still choose 1080p by hand. Reach for it to hold down bandwidth on a stream that would otherwise climb to 4K, or to keep a background or thumbnail player cheap.

Renditions are matched on pixel area rather than height, which keeps unusual aspect ratios honest: an ultrawide 2560×1080 rendition carries more pixels than 16:9 1080p, so a `'1080p'` cap leaves it out. When every rendition sits above the cap, the smallest one plays.

Changing the cap applies to the running engine, so playback continues uninterrupted. It needs the hls.js engine — native HLS playback ignores it, and audio-only streams have no video renditions to cap.

### Capping to the player’s size

A 400px-wide player has no use for a 4K rendition, so `capRenditionToPlayerSize` holds automatic selection to the smallest rendition that still covers the element. It defaults to `true`, and the cap follows the element as it’s resized:

```tsx
<HlsJsVideo source={{ src: 'https://example.com/stream.m3u8', capRenditionToPlayerSize: false }} />
```

The element is measured in device pixels, so a `2` device pixel ratio asks for twice the rendition a CSS measurement would — a 640px-wide player on a retina screen still gets 720p. Switch the cap off for a player whose layout size understates what it needs, such as one that goes fullscreen without a resize.

`minAutoResolution` bounds how far down that cap can reach, and defaults to `'720p'`:

```tsx
<HlsJsVideo source={{ src: 'https://example.com/stream.m3u8', minAutoResolution: '480p' }} />
```

**It is not a quality floor.** It bounds the size-derived cap and nothing else. When bandwidth is poor, adaptive selection still drops below it — the cap is a ceiling, and selection stays free underneath. It also never raises an explicit `maxAutoResolution`: ask for at most `'360p'` alongside a `'720p'` floor and you get `'360p'`.

The default is there because the low rungs of a ladder exist for poor network conditions, and capping a small player down to them looks worse than its size suggests. Name a lower rung to weaken the floor, or `'270p'` to lift it for any real ladder.

### Four things that sound alike

Four separate mechanisms bound which rendition plays, and they’re easy to mistake for each other:

| Option | Side | What it does |
| --- | --- | --- |
| `source.playback.maxResolution` | Server | A Mux query param. Trims the manifest, so higher renditions never arrive — not even by hand. |
| `source.maxAutoResolution` | Client | A ceiling on automatic selection. Everything still arrives and stays selectable by hand. |
| `source.capRenditionToPlayerSize` | Client | The same kind of ceiling, derived from the element’s rendered size and moving with it. |
| `source.minAutoResolution` | Client | A bound on the one above. Not a quality minimum, and not related to `playback.minResolution`. |

`playback.maxResolution` and `playback.minResolution` are the server-side pair: they decide what the manifest carries. The other three only bound what adaptive selection picks from whatever does arrive.

## DRM protected sources

Protected content is licensed through `source.drm`, keyed by EME key system id — alongside the URL rather than inside an engine’s namespace, because which engine plays the manifest is decided later and both paths read it:

```tsx
<HlsJsVideo
  source={{
    src: 'https://example.com/protected.m3u8',
    drm: {
      'com.apple.fps': {
        licenseUrl: 'https://license.example.com/fairplay',
        serverCertificateUrl: 'https://license.example.com/fairplay-cert',
      },
      'com.widevine.alpha': { licenseUrl: 'https://license.example.com/widevine' },
      'com.microsoft.playready': { licenseUrl: 'https://license.example.com/playready' },
    },
  }}
/>
```

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://videojs.org/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
<HlsJsVideo
  source={{
    src: 'https://example.com/protected.m3u8',
    drm: { 'com.apple.fps': { licenseUrl, serverCertificateUrl } },
    engine: {
      // hls.js licenses from here instead, and the native path still from `drm`.
      hlsJs: { drmSystems: { 'com.widevine.alpha': { licenseUrl: widevineLicenseUrl } } },
    },
  }}
/>
```

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://videojs.org/docs/framework/react/reference/components/mux-video) and [MuxAudio](https://videojs.org/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
<MuxVideo
  source={{
    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
    playback: { maxResolution: '1080p' },
    engine: { hlsJs: { maxBufferLength: 60 } },
  }}
  playsInline
/>
```

`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 source={{ playbackId, storyboard: { format: 'jpg' }, poster: { time: 12 } }} playsInline />
```

`MuxVideo` uses the storyboard itself, adding the thumbnail `<track>` 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
<MuxVideo
  source={{
    playbackId,
    playback: { token: playbackToken },
    drm: { token: drmToken },
  }}
  playsInline
/>
```

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?utm_source=videojs&utm_campaign=vjs10&utm_content=docs-content) 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
<MuxVideo
  source={{
    playbackId,
    playback: { token: playbackToken },
    // FairPlay and PlayReady from Mux, Widevine from your own server.
    drm: { token: drmToken, 'com.widevine.alpha': { licenseUrl: widevineLicenseUrl } },
  }}
  playsInline
/>
```

`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?utm_source=videojs&utm_campaign=vjs10&utm_content=docs-content), so a narrower still for a small viewport is a `width`:

```tsx
<MuxVideo source={{ playbackId, poster: { width: 320 } }} playsInline />
```

## Elements without engine options

[HlsVideo](https://videojs.org/docs/framework/react/reference/components/hls-video) and [HlsAudio](https://videojs.org/docs/framework/react/reference/components/hls-audio) take `src` or `source`, and the usual media props.

Their `source` carries only `src`, `type`, and `drm`, with no `engine`, `preferPlayback`, or rendition caps. They run on our own playback engine, which does not accept configuration from the element yet.

On HlsVideo, `drm` licenses FairPlay, Widevine, and PlayReady, taking the same license servers as [DRM protected sources](https://videojs.org/docs/framework/react/guides/media-sources#drm-protected-sources). HlsAudio accepts `drm` but ignores it, so one source object serves both.

## See also

- [HlsJsVideo element reference](https://videojs.org/docs/framework/react/reference/components/hlsjs-video)
- [MuxVideo element reference](https://videojs.org/docs/framework/react/reference/components/mux-video)
- [DashVideo element reference](https://videojs.org/docs/framework/react/reference/components/dash-video)

---

<!-- Source: https://videojs.org/docs/framework/react/guides/autoplay -->

# 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 component, 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 (
    <VideoPlayer>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline />
        <PlayButton
          className="media-play-button"
          render={(props, state) => (
            <button {...props}>{state.ended ? 'Replay' : state.paused ? 'Play' : 'Pause'}</button>
          )}
        />
      </Container>
    </VideoPlayer>
  );
}
```

**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://videojs.org/docs/framework/react/reference/components/video) and similar media components pass through to the underlying media element. The media element applies the props it supports and requests playback as soon as it has enough data.

The [playback feature](https://videojs.org/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://videojs.org/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://videojs.org/docs/framework/react/reference/api/feature-volume) reports support through `volumeAvailability`. It starts as `'unavailable'` before media attachment. On iOS Safari, it reports `'unsupported'`.
- 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

Use `BackgroundVideo` for an MP4 or WebM file, `HlsBackgroundVideo` for an HLS stream, or `MuxBackgroundVideo` for a complete Mux HLS URL.

These components default to muted, looping playback without player controls. Provide a separate motion control and respect reduced-motion preferences. For setup and motion controls, follow [Add a background video](https://videojs.org/docs/framework/react/guides/background-video). That guide also covers streaming backgrounds, which always autoplay and need conditional mounting.

### 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://videojs.org/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 (
    <button type="button" onClick={() => store.play().catch(console.error)}>
      Play video
    </button>
  );
}

export default function App() {
  return (
    <VideoPlayer>
      <Container>
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline />
        <StartPlaybackButton />
      </Container>
    </VideoPlayer>
  );
}
```

Calling `play()` directly from the click handler lets the browser authorize unmuted playback. The promise can still reject; these examples log the rejection and leave the button available to retry. For source and decoding failures, see [Handle playback errors](https://videojs.org/docs/framework/react/guides/playback-errors).

## 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. Give the user a [Mute button](https://videojs.org/docs/framework/react/reference/components/mute-button) to unmute through an explicit action. Unmuting without a user action can cause the browser to pause or block playback. A [Volume slider](https://videojs.org/docs/framework/react/reference/components/volume-slider) can also unmute where volume control is supported; it hides on platforms such as iOS Safari.

## Related pages

### Components

- [PlayButton](https://videojs.org/docs/framework/react/reference/components/play-button): Accessible play/pause button with keyboard support and customizable rendering
- [MuteButton](https://videojs.org/docs/framework/react/reference/components/mute-button): Accessible mute/unmute button with keyboard support and volume state reflection
- [BackgroundVideo](https://videojs.org/docs/framework/react/reference/components/background-video): Decorative background video element with automatic muting and looping
- [Controls](https://videojs.org/docs/framework/react/reference/components/controls): Container component for composing and auto-hiding video player controls on user interaction

### API

- [Playback](https://videojs.org/docs/framework/react/reference/api/feature-playback): Play/pause state and actions for the player store
- [Volume](https://videojs.org/docs/framework/react/reference/api/feature-volume): Volume level and mute state for the player store
- [usePlayer](https://videojs.org/docs/framework/react/reference/api/use-player): Hook to access the player store from within a Player

### Guides

- [Add a decorative background video](https://videojs.org/docs/framework/react/guides/background-video): Add an accessible background video from an MP4, WebM, HLS, or Mux source
- [Features](https://videojs.org/docs/framework/react/guides/features): The state and actions each feature adds to the player
- [Browser support](https://videojs.org/docs/framework/react/guides/browser-support): Browsers and rendering environments supported by Video.js 10, and how the packaged skins reach them

---

<!-- Source: https://videojs.org/docs/framework/react/guides/controls -->

# 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://videojs.org/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://videojs.org/docs/framework/react/guides/ui-components).

## Recommended approach

Wrap your control UI in [Controls](https://videojs.org/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 (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />

        <Controls.Root>
          <Controls.Backdrop className="controls-backdrop" />
          <Controls.Content className="media-controls">
            <Controls.Group className="controls-group" aria-label="Playback controls">
              <PlayButton
                className="button"
                render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
              />

              <Time.Value type="current" className="time" />
            </Controls.Group>
          </Controls.Content>
        </Controls.Root>
      </Container>
    </Player>
  );
}
```

**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]):not(:has(:focus-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://videojs.org/docs/framework/react/reference/api/feature-controls) tracks activity on the player container:

- `userActive` becomes `true` on pointer movement, keyboard input, or focus entry. It becomes `false` after two seconds without another activity event, or when the mouse leaves the container.
- `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(forceShow?)` marks the user inactive when controls are visible, and shows them otherwise. Pass `true` to show controls or `false` to mark the user inactive. Paused playback, a remote session, or an open menu can keep controls visible even when the user is inactive.

On touch devices, pointer movement does not show controls. A tap on the media toggles them, and movement during a gesture does not make them flicker.

The feature needs the player container for activity tracking. Without one, it keeps its initial active and visible state 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.
- Focus entry restarts the idle timer; holding focus alone does not keep controls visible. The example uses `:has(:focus-visible)` to keep controls visible while they contain keyboard focus. Focus from a mouse click does not hold them open.
- 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://videojs.org/docs/framework/react/reference/components/controls). This keeps the UI visible. When the controls feature is present, `userActive` still follows its activity tracking. The packaged audio skins use this mode.

```tsx
<Controls.Root visibility="always">
  <Controls.Content className="controls">...</Controls.Content>
</Controls.Root>
```

### Custom show/hide styling

Style the visible and hidden states in CSS with a fade, slide, or scale, using the component’s `data-visible` attribute. The controls feature handles the idle timer.

Keep controls with keyboard focus visible in your hiding rule:

```css
.media-controls:not([data-visible]):not(:has(:focus-visible)) {
  opacity: 0;
}
```

## Troubleshooting

### Controls never hide

Check for these causes:

- The media is paused. Controls stay visible by design.
- A remote playback session is active.
- An open menu or popover holds a controls lock.
- Something keeps triggering activity, such as a focused element inside the container that receives repeated events.

With the `:has(:focus-visible)` CSS rule above, keyboard focus keeps the controls visible even after activity becomes idle. Move focus out of the controls to let them hide.

### 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). When two handlers both toggle controls, one shows them and the other hides them again. Remove extra tap handlers that duplicate the built-in behavior. See [Add keyboard shortcuts and gestures](https://videojs.org/docs/framework/react/guides/keyboard-shortcuts).

## Related pages

### Components

- [Controls](https://videojs.org/docs/framework/react/reference/components/controls): Container component for composing and auto-hiding video player controls on user interaction
- [Container](https://videojs.org/docs/framework/react/reference/components/player-container): The player's visual and interaction surface for layout, fullscreen, focus, and user activity.

### API

- [Controls](https://videojs.org/docs/framework/react/reference/api/feature-controls): User activity and controls visibility state for the player store

### Guides

- [Add keyboard shortcuts and gestures](https://videojs.org/docs/framework/react/guides/keyboard-shortcuts): Add keyboard shortcuts, tap and double-tap gestures, and on-screen feedback for input actions.
- [Accessibility](https://videojs.org/docs/framework/react/guides/accessibility): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player

---

<!-- Source: https://videojs.org/docs/framework/react/guides/poster -->

# Add a poster and loading placeholder

Set the image shown before playback, then add a lightweight placeholder while it loads

A poster is the image shown before your video plays. There are several places to set one, so work down this list and stop at the first step that fits:

1. **Let the media provide it.** Some media components create a poster from the source, so there is nothing extra to host or keep in sync.
2. **Set `poster` on the player.** With a packaged skin, that is all a static image needs.
3. **Take control of the image** when you need a framework image component, a `<picture>` element, or a loading placeholder. The skin renders your image instead of its own.
4. **Keep it working after [adding the skin source to your project](https://videojs.org/docs/framework/react/guides/customize-skins#style-skin-source).** The player’s `poster` still reaches the Poster component your skin renders. You can also set the image’s source yourself.

## Let the media provide a poster

Some media components choose a poster for you. For example, `MuxVideo` creates one from its playback ID:

Install the React façade and the Mux playback adapter:

```bash
pnpm add @videojs/react @videojs/mux-video
```

```tsx
import '@videojs/react/video/skin.css';
import { MuxVideo } from '@videojs/react/media/mux-video';
import { VideoPlayer, VideoSkin } from '@videojs/react/video';

export function MyPlayer() {
  return (
    <VideoPlayer>
      <VideoSkin>
        <MuxVideo
          source={{
            playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
            poster: { time: 2 },
          }}
          playsInline
        />
      </VideoSkin>
    </VideoPlayer>
  );
}
```

## Set a poster on the player

When the media has no poster of its own, set the player’s `poster` to an image URL:

```tsx
import '@videojs/react/video/skin.css';
import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';

export function MyPlayer() {
  return (
    <VideoPlayer poster="/poster.jpg">
      <VideoSkin>
        <Video src="/video.mp4" playsInline />
      </VideoSkin>
    </VideoPlayer>
  );
}
```

A packaged skin includes [Poster](https://videojs.org/docs/framework/react/reference/components/poster) and shows the image automatically. If you build your own UI, add Poster yourself. The poster 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://videojs.org/docs/framework/react/reference/api/feature-metadata) for how the player combines those values.

Set `poster` on the player to supply the skin’s image. A `poster` on the native `<video>` or React `Video` sets only the browser’s poster; it does not populate the player’s Poster component, `renderPoster`, or the HTML poster slot.

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

When a plain `<img>` is not enough, give the packaged skin an image of your own:

Pass a `renderPoster` callback to the skin. It receives two arguments: image props and poster state. Forward the image props, including the ref and load handlers, so Video.js can track the image. Read `src` from the poster state; it is an empty string until a poster URL resolves. For Next.js:

```tsx
'use client';

import '@videojs/react/video/skin.css';
import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
import NextImage from 'next/image';

export function MyPlayer() {
  return (
    <VideoPlayer poster="/poster.jpg">
      <VideoSkin
        renderPoster={(props, { src }) =>
          src ? <NextImage {...props} src={src} alt="" fill /> : null
        }
      >
        <Video src="/video.mp4" playsInline />
      </VideoSkin>
    </VideoPlayer>
  );
}
```

## Add a loading placeholder

A placeholder is a tiny preview that appears while the poster downloads, so a slow poster does not leave the player as empty space. Keep it small enough to include directly in the page, for example as a short data URL. Add it to the customized image from the previous section.

Replace `data:image/webp;base64,…` in the examples below with a complete data URL generated from your poster.

### Use your framework’s image component

If your image component supports placeholders, pass yours through `renderPoster`:

```tsx
'use client';

import '@videojs/react/video/skin.css';
import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
import NextImage from 'next/image';

export function MyPlayer() {
  return (
    <VideoPlayer poster="/poster.jpg">
      <VideoSkin
        renderPoster={(props, { src }) =>
          src ? (
            <NextImage
              {...props}
              src={src}
              alt=""
              fill
              placeholder="blur"
              blurDataURL="data:image/webp;base64,…"
            />
          ) : null
        }
      >
        <Video src="/video.mp4" playsInline />
      </VideoSkin>
    </VideoPlayer>
  );
}
```

Next.js can generate blur data for supported static image imports. For a poster URL supplied at runtime, provide `blurDataURL` yourself. Configure [`remotePatterns`](https://nextjs.org/docs/app/api-reference/components/image#remotepatterns) in Next.js if the poster comes from another origin.

### Use a plain image

For more control, add the placeholder as a background on the image that `VideoSkin` draws:

```tsx
import '@videojs/react/video/skin.css';
import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';

export function MyPlayer() {
  return (
    <VideoPlayer poster="/poster.jpg">
      <VideoSkin
        renderPoster={(props) => (
          <img
            {...props}
            style={{
              ...props.style,
              background:
                "url('data:image/webp;base64,…') var(--media-object-position, center) / contain no-repeat",
            }}
          />
        )}
      >
        <Video src="/video.mp4" playsInline />
      </VideoSkin>
    </VideoPlayer>
  );
}
```

The examples use `contain` for both images. Use `cover` for both when the poster should fill the player. Keeping the same size and position prevents the image from jumping when the poster appears.

## Set the poster after adding skin source

After you add the skin source to your project, the first two approaches still work. The player’s `poster`, or the poster the media provides, reaches the [Poster](https://videojs.org/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. You can also set image attributes, such as `sizes` and `loading`. If you provide your own `src` or `srcSet`, Video.js leaves the image alone.

Keep your skin’s existing classes and apply a placeholder through the image’s `render` prop:

```tsx
<Poster.Root className="media-poster">
  <Poster.Image
    className="media-poster-image"
    render={(props) => (
      <img
        {...props}
        style={{
          ...props.style,
          background:
            "url('data:image/webp;base64,…') var(--media-object-position, center) / contain no-repeat",
        }}
      />
    )}
  />
</Poster.Root>
```

## Troubleshooting

### No poster appears

Check that the player has a `poster` or that the media component can create one from its source.

A `poster` set only on the native media element does not reach the skin’s Poster. Move that URL to the player’s `poster`.

### The final poster never appears

Pass `src` from the callback’s second argument 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://videojs.org/docs/framework/react/reference/components/poster): Poster image component that displays a thumbnail until video playback starts

### API

- [Metadata](https://videojs.org/docs/framework/react/reference/api/feature-metadata): Resolved title and poster values for the player store

### Guides

- [Customize skins](https://videojs.org/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://videojs.org/docs/framework/react/guides/build-your-own-component): Create custom player controls that read state, dispatch actions, and stay accessible.

---

<!-- Source: https://videojs.org/docs/framework/react/guides/captions -->

# 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://videojs.org/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://videojs.org/docs/framework/react/guides/ui-components).

## Recommended approach

Add WebVTT tracks as `<track>` children of the media component, and give users a [CaptionsButton](https://videojs.org/docs/framework/react/reference/components/captions-button) to toggle them.

The `<track>` loads `/docs/demos/text-tracks/captions.vtt`, shown in the `captions.vtt` tab. Host a WebVTT file for your video and point `src` at its URL.

**App.tsx**

```tsx
import { CaptionsButton, Container } from '@videojs/react';
import { Video, VideoPlayer } from '@videojs/react/video';

export default function BasicUsage() {
  return (
    <VideoPlayer>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop>
          <track kind="captions" src="/docs/demos/text-tracks/captions.vtt" srcLang="en" label="English" default />
        </Video>
        <CaptionsButton
          className="media-captions-button"
          render={(props, state) => (
            <button {...props}>{state.subtitlesShowing ? 'Captions Off' : 'Captions On'}</button>
          )}
        />
      </Container>
    </VideoPlayer>
  );
}
```

**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);
}
```

**captions.vtt**

```text
WEBVTT

00:00.000 --> 00:03.000
This is a demo of the captions button.

00:03.000 --> 00:06.000
Captions help make video accessible to everyone.

00:06.000 --> 00:09.000
Toggle captions on and off with a single click.
```

## How it works

The [text track feature](https://videojs.org/docs/framework/react/reference/api/feature-text-tracks) mirrors the media component’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?)` hides captions if a caption or subtitle track is showing. Otherwise it shows one track, chosen in this order: the last track shown, a track matching the browser language, then the first available track. Pass `true` or `false` to force captions on or off.
- `selectSubtitlesTrack(id)` shows one track and disables the rest; pass `null` to disable all.

Tracks don’t have to come from `<track>` 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 component.
- Track selection UIs identify tracks by `label` and `language`; give every track both.
- `default` on a `<track>` marks it as the preferred initial track. The browser’s caption preferences can select another track.

## Common variations

### Language selection menu

For multiple languages, render a menu instead of a toggle.

Add a `<track>` for each language, then render `CaptionsMenu` inside `Container`. `useCaptionsOptions` returns an “Off” option, one option per caption or subtitle track, and the current selection. `Menu.Content` must sit inside `Menu.Popup`, which positions it against the trigger:

**CaptionsMenu.tsx**

```tsx
import { Menu, useCaptionsOptions } from '@videojs/react';

export default function CaptionsMenu() {
  const captions = useCaptionsOptions();
  if (captions?.state.availability !== 'available') return null;

  return (
    <Menu.Root side="top" align="end">
      <Menu.Trigger render={<button type="button" />}>{captions.label}</Menu.Trigger>
      <Menu.Popup>
        <Menu.Content>
          <Menu.RadioGroup value={captions.value} onValueChange={captions.setValue} aria-label={captions.label}>
            {captions.options.map((option) => (
              <Menu.RadioItem key={option.value} value={option.value} disabled={option.disabled}>
                {option.label}
              </Menu.RadioItem>
            ))}
          </Menu.RadioGroup>
        </Menu.Content>
      </Menu.Popup>
    </Menu.Root>
  );
}
```

To show the selected track in the trigger, use the [CaptionsRadioGroup](https://videojs.org/docs/framework/react/reference/components/captions-radio-group) parts.

## 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 component.

### The captions menu doesn’t render

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://videojs.org/docs/framework/react/reference/components/captions-button): Accessible captions toggle button with availability detection and state reflection
- [CaptionsRadioGroup](https://videojs.org/docs/framework/react/reference/components/captions-radio-group): A menu radio group for selecting caption and subtitle tracks
- [Menu](https://videojs.org/docs/framework/react/reference/components/menu): A composable menu component for settings, option selection, and actions

### API

- [Text tracks](https://videojs.org/docs/framework/react/reference/api/feature-text-tracks): Subtitles, captions, and chapter track state for the player store
- [useCaptionsOptions](https://videojs.org/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://videojs.org/docs/framework/react/guides/thumbnails): Preview frames along the timeline while the user scrubs, powered by a storyboard track.
- [Media sources](https://videojs.org/docs/framework/react/guides/media-sources): Set what a media component plays and how its engine plays it with the structured source property
- [Accessibility](https://videojs.org/docs/framework/react/guides/accessibility): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player

---

<!-- Source: https://videojs.org/docs/framework/react/guides/keyboard-shortcuts -->

# 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://videojs.org/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://videojs.org/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 packaged skins include bindings suited to their player preset.

```tsx
import { Container, Gesture, Hotkey } from '@videojs/react';
import { Video, VideoPlayer } from '@videojs/react/video';

export default function App() {
  return (
    <VideoPlayer>
      <Container>
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />

        <Hotkey keys="Space" action="togglePaused" />
        <Hotkey keys="m" action="toggleMuted" />
        <Hotkey keys="f" action="toggleFullscreen" />
        <Hotkey keys="ArrowRight" action="seekStep" value={5} />
        <Hotkey keys="ArrowLeft" action="seekStep" value={-5} />

        <Gesture type="tap" action="togglePaused" pointer="mouse" region="center" />
        <Gesture type="tap" action="toggleControls" pointer="touch" />
        <Gesture type="doubletap" action="seekStep" value={-10} region="left" />
        <Gesture type="doubletap" action="seekStep" value={10} region="right" />
      </Container>
    </VideoPlayer>
  );
}
```

## How it works

- `Hotkey` binds keys to player actions: `togglePaused`, `toggleMuted`, `toggleFullscreen`, `toggleSubtitles`, `togglePictureInPicture`, `seekStep`, `volumeStep`, `seekToPercent`, `speedUp`, and `speedDown`. `seekStep` and `volumeStep` use a default step unless you pass a custom `value`. These input actions call the feature actions your components use; for example, `toggleFullscreen` chooses `requestFullscreen` or `exitFullscreen` based on `isFullscreen`.
- `Gesture` binds `tap` and `doubletap` to the same actions. Gestures also support `toggleControls`; `seekToPercent` is available only to hotkeys. Scope each binding with `pointer` (`mouse` or `touch`) and `region` (`left`, `center`, `right`). For example, a double tap on the left can rewind while a double tap on the right skips forward.
- `StatusAnnouncer` announces action results to screen readers. The input indicator components show brief on-screen feedback, such as volume level or captions on and off, the way native players do. The packaged skins include both.

The on-demand video skins bind these keys:

- Space and `k`: play and pause
- `m`: mute
- `f`: fullscreen
- `c`: captions
- `i`: picture-in-picture
- Left and Right arrows, `j` and `l`: seek 10 seconds
- Up and Down arrows: volume
- `0`–`9`: jump to a percentage
- `<` and `>`: speed

Live video skins keep the playback, mute, volume, fullscreen, captions, and picture-in-picture shortcuts. They omit seeking and speed shortcuts.

How the container splits into regions depends on which regions you bind for the same gesture type and pointer type. Left and right bindings divide the container into halves. Adding a center binding divides it into thirds. A center-only binding covers the whole container; a left-only or right-only binding covers that half. These regions use the container’s width, not the rendered video’s width.

## 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.
- Use only one of `toggleControls` and `togglePaused` for tap bindings with the same pointer type. The packaged skins pause on a mouse tap and toggle controls on a touch tap, matching platform conventions.
- Declared gestures and the built-in touch handling share one recognizer. Use the gesture components to add bindings. Extra raw pointer listeners can toggle controls twice.

## Common variations

### Customize a shortcut

For a packaged skin, [add the skin source to your project](https://videojs.org/docs/framework/react/guides/customize-skins#style-skin-source) and edit its `Hotkey` declarations. Adding another binding alongside the packaged skin does not replace its bindings. For a custom UI, edit your own `Hotkey` set directly.

### Seek step size

Set the `seekStep` distance with `value`. Match it to your content: 5 seconds for short clips, 15 or 30 seconds for long-form video.

## 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

The built-in recognizer delays a matching single tap and cancels it when a double tap occurs. Check that your tap and double-tap bindings use compatible `pointer` filters. Remove separate click handlers that also toggle playback, and avoid native video controls on the same gesture surface.

### No visual feedback on keyboard actions

The input indicator components render that feedback; use a packaged skin or add `StatusAnnouncer` and the indicator components from the skin source to a custom UI.

## Related pages

### Components

- [Controls](https://videojs.org/docs/framework/react/reference/components/controls): Container component for composing and auto-hiding video player controls on user interaction
- [Tooltip](https://videojs.org/docs/framework/react/reference/components/tooltip): A tooltip component for displaying contextual labels on hover and focus

### API

- [Playback](https://videojs.org/docs/framework/react/reference/api/feature-playback): Play/pause state and actions for the player store
- [Volume](https://videojs.org/docs/framework/react/reference/api/feature-volume): Volume level and mute state for the player store
- [Fullscreen](https://videojs.org/docs/framework/react/reference/api/feature-fullscreen): Fullscreen state and actions for the player store

### Guides

- [Automatically show and hide controls](https://videojs.org/docs/framework/react/guides/controls): Show controls while the user is active, hide them during playback, and toggle them by touch.
- [Accessibility](https://videojs.org/docs/framework/react/guides/accessibility): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player

---

<!-- Source: https://videojs.org/docs/framework/react/guides/live-streams -->

# Play live streams

Play live streams with live-edge tracking, DVR windows, and stream-type detection.

> **Note**
>
> Using a pre-built [skin](https://videojs.org/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://videojs.org/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 component, 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 (
    <LiveVideoPlayer>
      <Container>
        <HlsJsVideo src="https://your-stream.example.com/live.m3u8" autoPlay muted playsInline />
        <LiveButton render={(props, state) => <button {...props}>{state.liveEdge ? 'LIVE' : 'Go live'}</button>} />
      </Container>
    </LiveVideoPlayer>
  );
}
```

The examples use [`HlsJsVideo`](https://videojs.org/docs/framework/react/reference/components/hlsjs-video). The smaller [`HlsVideo`](https://videojs.org/docs/framework/react/reference/components/hls-video) also reports live state; use it when its supported feature set fits your stream.

The `liveVideoFeatures` bundle starts from [`videoFeatures`](https://videojs.org/docs/framework/react/guides/features), adds the live feature, and omits playback rate, 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://videojs.org/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://videojs.org/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` describes the kind of live window: `0` for a sliding window, `Infinity` for an event with playback history, and `NaN` for on-demand or unknown content. Read `seekable` to find the actual times viewers can rewind to.

The [time feature](https://videojs.org/docs/framework/react/reference/api/feature-time) replaces an infinite media duration with the end of the seekable range. That end advances as new segments become available; the start can also advance as old segments expire.

LiveButton treats playback as live when the playhead is no more than five seconds behind `liveEdgeStart`. If `liveEdgeStart` is unknown, the button uses the last ten seconds of the seekable range instead. When playback is farther behind, activating the button seeks to the seekable end. The button is disabled (`data-disabled`) when the media is not live or has no finite seekable end. At the edge, it is inactive (`aria-disabled="true"`).

## Availability and constraints

- `liveEdgeStart` and `targetLiveWindow` require media that implements the live capability. Examples include [hls.js video](https://videojs.org/docs/framework/react/reference/components/hlsjs-video), [SPF HLS video](https://videojs.org/docs/framework/react/reference/components/hls-video), [native HLS video](https://videojs.org/docs/framework/react/reference/components/native-hls-video), and [Shaka video](https://videojs.org/docs/framework/react/reference/components/shaka-video). Native HLS video requires browser HLS support. A plain `<video>` can report a live `streamType` from its duration, but its live-window values stay `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.
- Both sliding live windows and growing event histories can support seeking. Check `seekable` for the available range. The built-in time slider starts at zero, so use it only while the seekable history starts at zero; a moving start requires a custom slider.
- `liveVideoFeatures` omits playback rate control. Add it explicitly if your DVR UI needs it.

## Common variations

### DVR: let users scrub back

For a live event whose seekable history starts at zero, add a [TimeSlider](https://videojs.org/docs/framework/react/reference/components/time-slider) to your custom UI or [customized live skin](https://videojs.org/docs/framework/react/guides/customize-skins#style-skin-source). Its maximum follows the seekable end. For a sliding window whose start moves forward, build a slider from the current `seekable` start and end; the built-in slider would include expired times.

### 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://videojs.org/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 <LiveButton render={(props, state) => <button {...props}>{state.liveEdge ? 'LIVE' : 'Go live'}</button>} />;
}

export default function App() {
  return (
    <Player>
      <Container>
        <HlsJsVideo src="https://your-stream.example.com/live.m3u8" autoPlay muted playsInline />
        <LiveBadge />
      </Container>
    </Player>
  );
}
```

## Troubleshooting

### The live badge never activates

LiveButton reads `targetLiveWindow`, `currentTime`, and `seekable`. Confirm that `targetLiveWindow` is `0` or `Infinity` and that `seekable` has a finite end. Use a live-capable media component such as [HlsJsVideo](https://videojs.org/docs/framework/react/reference/components/hlsjs-video). The live button does not need `streamTypeFeature`; add it only when your own UI reads `streamType`.

### 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

Compare the slider’s range with `seekable`. The built-in slider always starts at zero. Once a sliding window moves past zero, the slider’s range includes expired history. Use a custom slider that follows both range bounds, or keep the live button without a timeline.

## Related pages

### Components

- [TimeSlider](https://videojs.org/docs/framework/react/reference/components/time-slider): A slider component for seeking through media playback time
- [BufferingIndicator](https://videojs.org/docs/framework/react/reference/components/buffering-indicator): Loading indicator that displays when the video player is buffering or waiting for data

### API

- [Live](https://videojs.org/docs/framework/react/reference/api/feature-live): Live edge state for the player store
- [Stream type](https://videojs.org/docs/framework/react/reference/api/feature-stream-type): Stream delivery type (live / on-demand) state for the player store
- [Time](https://videojs.org/docs/framework/react/reference/api/feature-time): Playback position and duration state for the player store
- [HlsJsVideo](https://videojs.org/docs/framework/react/reference/components/hlsjs-video): HLS video element powered by hls.js for adaptive bitrate streaming

### Guides

- [Media sources](https://videojs.org/docs/framework/react/guides/media-sources): Set what a media component plays and how its engine plays it with the structured source property

---

<!-- Source: https://videojs.org/docs/framework/react/guides/quality -->

# 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://videojs.org/docs/framework/react/guides/media-sources).

> **Note**
>
> Using a pre-built [skin](https://videojs.org/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://videojs.org/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, QualityRadioGroup } from '@videojs/react';
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
import { videoFeatures } from '@videojs/react/video';
import type { ReactNode } from 'react';

const { Player } = createPlayer({ features: videoFeatures });
const src = 'https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4.m3u8';

function QualityMenu(): ReactNode {
  return (
    <Menu.Root side="top" align="end">
      <QualityRadioGroup.Root>
        <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
          Quality
          <QualityRadioGroup.Value className="menu-hint" />
        </Menu.Trigger>
        <Menu.Popup className="menu">
          <Menu.Content>
            <QualityRadioGroup.Options
              className="menu-group"
              renderItem={(props, item) => (
                <Menu.RadioItem {...props} className="menu-item">
                  <span>
                    {item.label}
                    {item.tier ? <sup className="menu-tier">{item.tier}</sup> : null}
                  </span>
                  {item.badge ? <span className="menu-badge">{item.badge}</span> : null}
                  <Menu.ItemIndicator checked={item.checked} forceMount className="menu-indicator">
                    ✓
                  </Menu.ItemIndicator>
                </Menu.RadioItem>
              )}
            />
          </Menu.Content>
        </Menu.Popup>
      </QualityRadioGroup.Root>
    </Menu.Root>
  );
}

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <HlsJsVideo src={src} autoPlay crossOrigin="anonymous" muted playsInline loop />
        <div className="menu-bar">
          <QualityMenu />
        </div>
      </Container>
    </Player>
  );
}
```

**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://videojs.org/docs/framework/react/reference/api/feature-quality) mirrors the media component’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(id)` pins one rendition by its `id` from `videoRenditionList`; pass `'auto'` to return control to the engine’s adaptive selection.

[`useQualityOptions`](https://videojs.org/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

- The live preset omits `qualityFeature` and cannot accept extra features. To add a quality menu to a live player, use `createPlayer` with `[...liveVideoFeatures, qualityFeature]`. See [Play live streams](https://videojs.org/docs/framework/react/guides/live-streams) for custom player setup.
- 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.
- Pinning a high rendition on a slow connection causes buffering: the engine can no longer step down. Keep “Auto” the default.
- Loading a new source replaces the rendition list and resets the selection.

## 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.

### Pin quality programmatically

Call `selectVideoRendition` to hold one rendition until the user selects “Auto”. To limit resolution while keeping automatic switching, set `maxAutoResolution` on the source. It needs the hls.js engine; native HLS playback ignores it. See [Options Video.js normalizes](https://videojs.org/docs/framework/react/guides/media-sources#options-videojs-normalizes).

```tsx
import { Container, createPlayer, useQualityOptions } from '@videojs/react';
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
import { videoFeatures } from '@videojs/react/video';

const { Player, usePlayer } = createPlayer({ features: videoFeatures });

function PinLowestRendition() {
  const store = usePlayer();
  const renditions = usePlayer((s) => s.videoRenditionList);
  const quality = useQualityOptions();

  const lowest = [...renditions].sort((a, b) => (a.height ?? 0) - (b.height ?? 0))[0];
  if (quality?.state.availability !== 'available' || !lowest) return null;

  return (
    <button type="button" onClick={() => store.selectVideoRendition(lowest.id)}>
      Use lowest quality
    </button>
  );
}

export default function App() {
  return (
    <Player>
      <Container>
        <HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" muted playsInline />
        <PinLowestRendition />
      </Container>
    </Player>
  );
}
```

## Troubleshooting

### The quality menu doesn’t render

Confirm that the player includes `qualityFeature`. The live preset omits it; compose a custom player as described above.

Quality availability is `'unavailable'`. The source is progressive (no renditions), the manifest hasn’t loaded yet, or the media component doesn’t support renditions. Use a streaming media component such as [HlsVideo](https://videojs.org/docs/framework/react/reference/components/hls-video) or [HlsJsVideo](https://videojs.org/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://videojs.org/docs/framework/react/reference/components/quality-radio-group): A menu radio group for selecting video quality
- [Menu](https://videojs.org/docs/framework/react/reference/components/menu): A composable menu component for settings, option selection, and actions

### API

- [Quality](https://videojs.org/docs/framework/react/reference/api/feature-quality): Video rendition state and actions for the player store
- [useQualityOptions](https://videojs.org/docs/framework/react/reference/api/use-quality-options): Hook to build video quality menu options from the player rendition state
- [HlsVideo](https://videojs.org/docs/framework/react/reference/components/hls-video): Lightweight HLS video element with minimal bundle size
- [HlsJsVideo](https://videojs.org/docs/framework/react/reference/components/hlsjs-video): HLS video element powered by hls.js for adaptive bitrate streaming
- [DashVideo](https://videojs.org/docs/framework/react/reference/components/dash-video): DASH video element powered by dash.js for adaptive bitrate streaming

### Guides

- [Media sources](https://videojs.org/docs/framework/react/guides/media-sources): Set what a media component plays and how its engine plays it with the structured source property

---

<!-- Source: https://videojs.org/docs/framework/react/guides/fullscreen -->

# 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://videojs.org/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://videojs.org/docs/framework/react/guides/ui-components).

## Recommended approach

Add a [FullscreenButton](https://videojs.org/docs/framework/react/reference/components/fullscreen-button) inside the player container. When element fullscreen is supported, it presents the whole container, including controls, captions, and overlays. On iPhone Safari, it uses the native video presentation instead.

**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 (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <FullscreenButton
          className="media-fullscreen-button"
          render={(props, state) => <button {...props}>{state.fullscreen ? 'Exit Fullscreen' : 'Fullscreen'}</button>}
        />
      </Container>
    </Player>
  );
}
```

**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://videojs.org/docs/framework/react/reference/api/feature-fullscreen) tracks fullscreen state and provides the actions:

- `isFullscreen` 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 component.
- `requestFullscreen()` and `exitFullscreen()` change the presentation. When the Fullscreen API is available, requests target the player container. Otherwise they fall back to the media element’s native presentation.

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, the button’s `data-fullscreen` attribute, or `isFullscreen` in player state.

The built-in button hides when `fullscreenAvailability` is not `'available'`. Use the same check for custom controls and handle rejected requests. When the attached media has no supported fullscreen method, the action resolves without changing the presentation.

## 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.

The preset has a fixed feature list, so build the player yourself with [`createPlayer`](https://videojs.org/docs/framework/react/reference/api/create-player):

```tsx
import { Container, createPlayer, FullscreenButton, orientationLockFeature } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({
  features: [...videoFeatures, orientationLockFeature],
});

export default function App() {
  return (
    <Player>
      <Container>
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
        <FullscreenButton>Fullscreen</FullscreenButton>
      </Container>
    </Player>
  );
}
```

To lock to something other than `landscape`, set `orientationLockType` on the player. See the [orientation lock feature](https://videojs.org/docs/framework/react/reference/api/feature-orientation-lock) reference for details.

### Double-click to toggle

Use the `Gesture` component — the packaged skins ship this exact binding. Keep the button as the accessible path; gestures are a pointer-only shortcut.

```tsx
import { Gesture } from '@videojs/react';

<Gesture type="doubletap" action="toggleFullscreen" region="center" />
```

With left, center, and right double-tap bindings for the same pointer type, `region="center"` covers the middle third, as in the on-demand video skins. A center-only double-tap binding covers the whole surface. See [Add keyboard shortcuts and gestures](https://videojs.org/docs/framework/react/guides/keyboard-shortcuts) for region behavior.

## Troubleshooting

### The fullscreen button doesn’t render

The button hides while `fullscreenAvailability` is `'unavailable'` or `'unsupported'`. Wait for media attachment, check browser support, and confirm that an embedding iframe permits fullscreen with `allow="fullscreen"`.

### The fullscreen request is rejected

Call the action directly from a click handler and check that an embedding iframe permits fullscreen with `allow="fullscreen"`. Handle the returned promise’s rejection. To detect unsupported fullscreen, check `fullscreenAvailability`; an unsupported request can resolve without entering 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://videojs.org/docs/framework/react/reference/components/fullscreen-button): Accessible fullscreen toggle button with keyboard support and state reflection
- [Container](https://videojs.org/docs/framework/react/reference/components/player-container): The player's visual and interaction surface for layout, fullscreen, focus, and user activity.

### API

- [Fullscreen](https://videojs.org/docs/framework/react/reference/api/feature-fullscreen): Fullscreen state and actions for the player store
- [Orientation lock](https://videojs.org/docs/framework/react/reference/api/feature-orientation-lock): Screen orientation locking while fullscreen is active

### Guides

- [Use picture-in-picture](https://videojs.org/docs/framework/react/guides/picture-in-picture): Pop the video into a floating window, with availability detection and state that tracks every entry path.

---

<!-- Source: https://videojs.org/docs/framework/react/guides/picture-in-picture -->

# 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://videojs.org/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://videojs.org/docs/framework/react/guides/ui-components).

## Recommended approach

Add a [PiPButton](https://videojs.org/docs/framework/react/reference/components/pip-button). It requests and exits picture-in-picture, reflects the current state, and stays hidden until picture-in-picture is available.

**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 (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <PiPButton
          className="media-pip-button"
          render={(props, state) => <button {...props}>{state.pip ? 'Exit PiP' : 'Enter PiP'}</button>}
        />
      </Container>
    </Player>
  );
}
```

**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://videojs.org/docs/framework/react/reference/api/feature-pip) puts three things in player state.

`isPictureInPicture` 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.

`pictureInPictureAvailability` starts as `'unavailable'`. It becomes `'available'` when the media supports picture-in-picture and has loaded metadata, or `'unsupported'` when the browser or media has no supported route. Loading a new source returns it to `'unavailable'` until metadata loads.

`requestPictureInPicture()` and `exitPictureInPicture()` change the presentation. Handle rejected promises when the browser blocks a request. An entry request before metadata loads rejects with `InvalidStateError`. Without a supported API, the request resolves without opening a window.

Picture-in-picture and fullscreen are exclusive: requesting one exits the other first.

## Availability and constraints

If a Safari standalone web app exposes the standard Picture-in-Picture API, Video.js still reports picture-in-picture as `'unsupported'`. The built-in button hides in that case. Check `pictureInPictureAvailability` in installed web apps as well as browser tabs.

- Show picture-in-picture controls only when `pictureInPictureAvailability` is `'available'`. PiPButton handles this for you.
- Requests must come from a user gesture; browsers reject requests outside one.
- [Firefox 153](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Releases/153) (July 2026) added the programmatic picture-in-picture API on desktop. On earlier desktop versions, including Firefox ESR 140, `pictureInPictureAvailability` is `'unsupported'`, even though Firefox shows users its own picture-in-picture toggle. Check `pictureInPictureAvailability` rather than inferring support from the browser version.
- 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 `isPictureInPicture` instead of assuming your button is the only entry and exit.

## Common variations

### Open picture-in-picture from your own button

Call `requestPictureInPicture()` directly in your button’s click handler so the browser treats the request as a user gesture. The action exits fullscreen first, then uses the standard Picture-in-Picture API or Safari’s presentation mode:

```tsx
import { Container, createPlayer, selectPiP } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player, usePlayer } = createPlayer({ features: videoFeatures });

function WatchElsewhereButton() {
  const pip = usePlayer(selectPiP);
  if (pip?.pictureInPictureAvailability !== 'available') return null;

  return (
    <button
      type="button"
      onClick={() => {
        pip.requestPictureInPicture().catch(() => {
          // Show your app's request-failed message.
        });
      }}
    >
      Keep watching while you browse
    </button>
  );
}

export default function App() {
  return (
    <Player>
      <Container>
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
        <WatchElsewhereButton />
      </Container>
    </Player>
  );
}
```

## Troubleshooting

### The picture-in-picture button doesn’t render

Check `pictureInPictureAvailability`. It is `'unavailable'` before metadata loads, and `'unsupported'` when the browser or media has no supported picture-in-picture route. Some embeds cannot enter picture-in-picture even in a browser that supports it.

### The request rejects

The request ran outside a user gesture, or the browser refused it. Handle the rejection. A request before metadata loads rejects with `InvalidStateError`; check `pictureInPictureAvailability` before offering your button.

### State is wrong after the user closes the floating window

Read `isPictureInPicture` 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://videojs.org/docs/framework/react/reference/components/pip-button): Accessible picture-in-picture toggle button with keyboard support and state reflection

### API

- [Picture-in-picture](https://videojs.org/docs/framework/react/reference/api/feature-pip): Picture-in-picture state and actions for the player store

### Guides

- [Go fullscreen and lock orientation](https://videojs.org/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://videojs.org/docs/framework/react/guides/casting): Send playback to AirPlay and Google Cast devices, with availability detection and connection state.

---

<!-- Source: https://videojs.org/docs/framework/react/guides/thumbnails -->

# 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://videojs.org/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://videojs.org/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://videojs.org/docs/framework/react/guides/ui-components).

## Recommended approach

Add a `<track kind="metadata" label="thumbnails" default>` whose cues reference storyboard images. Then put a slider thumbnail inside the [TimeSlider](https://videojs.org/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://videojs.org/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.

**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 (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop crossOrigin="anonymous">
          <track kind="metadata" label="thumbnails" src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt" default />
        </Video>
        <TimeSlider.Root className="media-time-slider">
          <TimeSlider.Track className="media-slider-track">
            <TimeSlider.Fill className="media-slider-fill" />
          </TimeSlider.Track>
          <Slider.Thumbnail.Root className="media-slider-thumbnail">
            <Slider.Thumbnail.Image className="media-slider-thumbnail-image" />
          </Slider.Thumbnail.Root>
        </TimeSlider.Root>
      </Container>
    </Player>
  );
}
```

**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://videojs.org/docs/framework/react/reference/api/feature-text-tracks) exposes this track as `thumbnailsTrack`, with its `cues` and `src`.
- 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://videojs.org/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 component 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.

## Common variations

### Customize the skin’s thumbnail image

Inside a packaged skin, pass `renderThumbnail` to draw the image yourself; the skin still supplies `src` and sizing:

```tsx
<VideoSkin renderThumbnail={<img alt="" loading="lazy" fetchPriority="low" />} />
```

## 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 component.

### 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://videojs.org/docs/framework/react/reference/components/thumbnail): Time-based thumbnail preview component for timeline scrubbing and hover previews
- [Slider](https://videojs.org/docs/framework/react/reference/components/slider): A composable slider component with track, fill, thumb, preview, and value parts
- [TimeSlider](https://videojs.org/docs/framework/react/reference/components/time-slider): A slider component for seeking through media playback time

### API

- [Text tracks](https://videojs.org/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://videojs.org/docs/framework/react/guides/poster): Set the image shown before playback, then add a lightweight placeholder while it loads
- [Show captions and subtitles](https://videojs.org/docs/framework/react/guides/captions): Show captions and subtitles, and let users turn them on and pick a language.

---

<!-- Source: https://videojs.org/docs/framework/react/guides/casting -->

# 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://videojs.org/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://videojs.org/docs/framework/react/guides/ui-components).

## Installation

Install the Google Cast extension and the hls.js adapter used in the example below. AirPlay needs no extra package:

```bash
pnpm add @videojs/react @videojs/google-cast @videojs/hlsjs-video
```

## Recommended approach

Use the [GoogleCast extension](https://videojs.org/docs/framework/react/reference/components/google-cast) with a [CastButton](https://videojs.org/docs/framework/react/reference/components/cast-button), and add an [AirPlayButton](https://videojs.org/docs/framework/react/reference/components/airplay-button) for Safari. The packaged skins already include both buttons; add `GoogleCast` anywhere inside the player to enable the configurable Cast route. It works with any media the player attaches, including a plain `<Video />`.

**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 (
    <Player>
      <Container className="media-container">
        <HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoPlay muted playsInline loop />
        <GoogleCast />
        <div className="media-remote-buttons">
          <AirPlayButton
            className="media-airplay-button"
            render={(props, state) => (
              <button {...props}>{state.state === 'connected' ? 'Stop AirPlay' : 'Start AirPlay'}</button>
            )}
          />
          <CastButton
            className="media-cast-button"
            render={(props, state) => (
              <button {...props}>{state.connection === 'connected' ? 'Stop casting' : 'Start casting'}</button>
            )}
          />
        </div>
      </Container>
    </Player>
  );
}
```

**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 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://videojs.org/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'`. The AirPlay route reports only `'disconnected'` and `'connected'`; Google Cast also reports `'connecting'`.
- `promptRemotePlayback()` opens the browser’s device picker, including during an active session. Use the picker to connect to a device or return to local playback.

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.

Control playback and read its state through the player while casting: use the built-in controls or the [store actions and state](https://videojs.org/docs/framework/react/reference/api/player-store) from `usePlayer`. Don’t call methods on the media component or listen for its events to drive or track a session.

For a custom control, call `promptRemotePlayback()` directly from the click handler and catch its promise. It rejects when no remote route exists or the browser refuses the request. A canceled Google Cast picker can also resolve without connecting, so show success only when `remotePlaybackState` is `'connected'`. The built-in buttons handle the request for you.

The Google Cast SDK loads only when the player includes the `GoogleCast` extension and runs in a Chromium browser that can cast.

## 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 its text tracks on its own. 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 component 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
<GoogleCast receiver="YOUR_APP_ID" />
```

Use `src` and `contentType` when the receiver should load a different source than the browser. A YouTube or Vimeo embed needs `src`: the receiver can’t play the embed itself, so without it nothing is sent to the receiver. `streamType` and `customData` let you describe that source and attach application-specific data. See the [GoogleCast reference](https://videojs.org/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.

### Custom UI shows local playback while casting

The code reads or controls the media component directly. Read playback state from the player store and call its actions instead; only the player reflects the remote session.

### The UI freezes on “connecting”

For Google Cast, track the `promptRemotePlayback()` promise separately from `remotePlaybackState`. Clear your loading indicator when the promise settles. A canceled picker can resolve without connecting. AirPlay does not expose a `'connecting'` phase; show its connected or disconnected state instead.

## Related pages

### Components

- [CastButton](https://videojs.org/docs/framework/react/reference/components/cast-button): Accessible Cast toggle button with state reflection and keyboard support
- [AirPlayButton](https://videojs.org/docs/framework/react/reference/components/airplay-button): Accessible AirPlay toggle button that opens the WebKit playback target picker and reflects session state
- [GoogleCast](https://videojs.org/docs/framework/react/reference/components/google-cast): Options for the Google Cast extension that configures the receiver and load request

### API

- [Remote Playback](https://videojs.org/docs/framework/react/reference/api/feature-remote-playback): Remote playback state and actions for the player store
- [HlsJsVideo](https://videojs.org/docs/framework/react/reference/components/hlsjs-video): HLS video element powered by hls.js for adaptive bitrate streaming

### Guides

- [Media sources](https://videojs.org/docs/framework/react/guides/media-sources): Set what a media component plays and how its engine plays it with the structured source property

---

<!-- Source: https://videojs.org/docs/framework/react/guides/playback-errors -->

# 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://videojs.org/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://videojs.org/docs/framework/react/guides/ui-components).

## Recommended approach

Render an [ErrorDialog](https://videojs.org/docs/framework/react/reference/components/error-dialog) inside the player container. It reads error state, presents the failure, and dismisses cleanly. The packaged skins include one.

```tsx
import { Container, ErrorDialog } from '@videojs/react';
import { Video, VideoPlayer } from '@videojs/react/video';

export default function App() {
  return (
    <VideoPlayer>
      <Container>
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />

        <ErrorDialog.Root>
          <ErrorDialog.Popup className="media-error">
            <ErrorDialog.Title />
            <ErrorDialog.Description />
            <ErrorDialog.Close>Dismiss</ErrorDialog.Close>
          </ErrorDialog.Popup>
        </ErrorDialog.Root>
      </Container>
    </VideoPlayer>
  );
}
```

## How it works

The [error feature](https://videojs.org/docs/framework/react/reference/api/feature-error) mirrors the media component’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 component 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.
- The feature records `error` events after attachment. An error already present on the media is not copied into state. Keep the error surface mounted regardless of playback state.

Server-rendered `<Video src={...}>` can start loading before hydration and player attachment. To capture startup failures, assign the source only after attachment. Alternatively, after attachment, check the native video’s `error` once through a ref and show an application message if it is already set.

## 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 the error.

### 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, usePlayer } from '@videojs/react';

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://videojs.org/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://videojs.org/docs/framework/react/reference/api/error-codes) for its trigger and v10 equivalent. These exceptions are separate from the player’s `error` state, which receives media playback errors after setup.

### Error code says the source isn’t supported

The browser can’t play the format through this media component. HLS in a plain video element outside Safari is the classic case; use the matching streaming media component. See [Media sources](https://videojs.org/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://videojs.org/docs/framework/react/reference/components/buffering-indicator): Loading indicator that displays when the video player is buffering or waiting for data

### API

- [Error](https://videojs.org/docs/framework/react/reference/api/feature-error): Media error state and actions for the player store

### Guides

- [Media sources](https://videojs.org/docs/framework/react/guides/media-sources): Set what a media component plays and how its engine plays it with the structured source property
- [Autoplay](https://videojs.org/docs/framework/react/guides/autoplay): Start playback automatically and handle browser autoplay restrictions.

---

<!-- Source: https://videojs.org/docs/framework/react/guides/user-preferences -->

# Remember user preferences

Save volume and caption preferences, restore them after loading, and adapt the pattern for quality selection.

Save preferences from player state to local storage or your backend. Video.js leaves storage and per-profile settings to your application.

## 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.

**VolumePersistence.tsx**

```tsx
import { Container, createPlayer } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';
import { useEffect, useRef, useState } from 'react';

export const { Player, usePlayer } = createPlayer({ features: videoFeatures });

const STORAGE_KEY = 'player:volume';

// Guard storage access so playback still works when storage is blocked.
function readSaved(): { volume: number; muted: boolean } | null {
  try {
    const value = JSON.parse(localStorage.getItem(STORAGE_KEY) ?? 'null');

    return Number.isFinite(value?.volume) && typeof value?.muted === 'boolean' ? value : 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);

        // Apply saved mute after setVolume, which unmutes above zero.
        if (saved.muted) store.setMuted(true);
      }

      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 (
    <Player>
      <Container>
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline />
        <VolumePersistence />
      </Container>
    </Player>
  );
}
```

## 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. The store batches notifications per microtask, so changes made in the same tick produce one callback. 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. To save a value, select it with `usePlayer` and write it to storage in an effect.
- 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`, `setMuted`, `selectSubtitlesTrack`, `selectVideoRendition`) rather than poking the media component, 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

- Video.js does not write preferences to storage. Initial values come from the media component, track markup, and playback engine.
- `setVolume` clamps to 0–1 and unmutes above zero. Restore volume first, then call `setMuted(true)` if the saved preference is muted. Calling `setMuted(false)` at zero raises the volume to 0.25.
- The volume examples leave autoplay off. For muted autoplay, defer volume restoration until a user action: restoring a positive volume unmutes the media and can interrupt autoplay, even if you immediately mute it again.
- `setVolume` and `setMuted` update `store.state` immediately. A React hook’s selected value updates on the next render.
- Track and rendition lists arrive when the media loads, not when the player is created. Subscribe and restore a saved selection when its entry appears in the list.
- On iOS Safari, `volumeAvailability` is `'unsupported'` after attachment. Restoring the volume level has no effect there; mute can still be restored.
- 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` because track ids can change between sources. Save `'off'` when captions are off. Restore once when the first caption or subtitle list arrives, then save later selection changes. Do not wait for `canPlay`. With limited preloading, `canPlay` can stay `false` until playback starts. Repeated restoration would override a selection the user already made.

If the saved language is absent from that first list, leave the stored preference intact until the selection changes. This example does not retry restoration when more tracks arrive; adapt the initial loading step if your engine exposes languages in several batches. Browser selection changes after restoration are saved just like user changes.

`CaptionsPersistence` imports `usePlayer` from `VolumePersistence.tsx` above. Render `<CaptionsPersistence />` next to `<VolumePersistence />` inside `Container`. Add a `<track>` with `label` and `srcLang` for each language to `Video`, as in [Show captions and subtitles](https://videojs.org/docs/framework/react/guides/captions). Remount `CaptionsPersistence` when changing sources, using a key derived from the source URL, so restoration runs again.

Omit `default` from these tracks when persisting caption preferences. A default track can turn on after restoration, causing this example to save its language over a stored `'off'` preference.

**CaptionsPersistence.tsx**

```tsx
import { useEffect, useRef, useState } from 'react';

import { usePlayer } from './VolumePersistence';

export default function CaptionsPersistence() {
  const store = usePlayer();
  const tracks = usePlayer((s) => s.textTrackList);
  const [saved] = useState(() => {
    try {
      return localStorage.getItem('player:captions');
    } catch {
      return null;
    }
  });
  const restored = useRef(false);
  const lastSelection = useRef<string | null>(null);

  useEffect(() => {
    const subtitles = tracks.filter((t) => t.kind === 'captions' || t.kind === 'subtitles');
    if (!subtitles.length) return;

    const showing = subtitles.find((t) => t.mode === 'showing');
    const selection = showing ? showing.language : 'off';

    // Restore once the first subtitle list arrives, then honor later changes.
    if (!restored.current) {
      const desired = saved === 'off' ? undefined : subtitles.find((t) => t.language === saved);

      restored.current = true;
      lastSelection.current = selection;

      if (saved && (desired || saved === 'off')) {
        store.selectSubtitlesTrack(desired?.id ?? null);
      }

      return;
    }

    // Save only later selection changes, preserving an unmatched preference.
    if (selection === lastSelection.current) return;

    lastSelection.current = selection;

    try {
      localStorage.setItem('player:captions', selection);
    } catch {
      // Continue without persistence when storage is blocked.
    }
  }, [store, tracks, saved]);

  return null;
}
```

### Remember a quality selection

Adapt the same restore-then-save pattern to the [quality feature](https://videojs.org/docs/framework/react/reference/api/feature-quality):

1. Save `'auto'` or the resolution of the selected entry in `videoRenditionList`. Read `selected`; `activeVideoRendition` can change during automatic playback and does not identify a manual preference.
2. Wait for the next source’s rendition list, then match the saved resolution to an entry. Rendition ids belong to that source, so do not reuse a saved id across sources.
3. Call `selectVideoRendition` with the matching entry’s id, or `'auto'` if no match exists. Every entry in `videoRenditionList` has an id; use it directly.
4. Do not save until restoration finishes; otherwise the source’s default selection overwrites the saved choice. After that, save each change the user makes.

To remember a data-saving limit while preserving automatic switching, persist `maxAutoResolution` and pass it on the next source. It needs the hls.js engine; native HLS playback ignores it. See [Options Video.js normalizes](https://videojs.org/docs/framework/react/guides/media-sources#options-videojs-normalizes).

### 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://videojs.org/docs/framework/react/reference/components/volume-slider): A slider component for controlling media playback volume
- [CaptionsRadioGroup](https://videojs.org/docs/framework/react/reference/components/captions-radio-group): A menu radio group for selecting caption and subtitle tracks
- [QualityRadioGroup](https://videojs.org/docs/framework/react/reference/components/quality-radio-group): A menu radio group for selecting video quality

### API

- [usePlayer](https://videojs.org/docs/framework/react/reference/api/use-player): Hook to access the player store from within a Player
- [useStore](https://videojs.org/docs/framework/react/reference/api/use-store): Hook to access store state and actions with optional selector-based subscriptions
- [Volume](https://videojs.org/docs/framework/react/reference/api/feature-volume): Volume level and mute state for the player store
- [Text tracks](https://videojs.org/docs/framework/react/reference/api/feature-text-tracks): Subtitles, captions, and chapter track state for the player store

### Guides

- [Show captions and subtitles](https://videojs.org/docs/framework/react/guides/captions): Show captions and subtitles, and let users turn them on and pick a language.
- [Add a quality selector](https://videojs.org/docs/framework/react/guides/quality): Read available renditions, let the engine adapt automatically, and offer manual quality selection.

---

<!-- Source: https://videojs.org/docs/framework/react/guides/background-video -->

# 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://videojs.org/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';
import { useEffect, useRef, useState } from 'react';

export default function BasicUsage() {
  const videoRef = useRef<HTMLVideoElement>(null);
  const [motionEnabled, setMotionEnabled] = useState(false);

  useEffect(() => {
    const preference = window.matchMedia('(prefers-reduced-motion: reduce)');
    const syncPreference = () => setMotionEnabled(!preference.matches);

    syncPreference();
    preference.addEventListener('change', syncPreference);

    return () => preference.removeEventListener('change', syncPreference);
  }, []);

  useEffect(() => {
    const video = videoRef.current;
    if (!video) return;

    let cancelled = false;

    if (motionEnabled) {
      video.play().catch(() => {
        if (!cancelled) setMotionEnabled(false);
      });
    } else {
      video.pause();
    }

    return () => {
      cancelled = true;
    };
  }, [motionEnabled]);

  return (
    <section className="add-background-video-react-demo" data-motion-enabled={motionEnabled ? '' : undefined}>
      <div className="add-background-video-react-demo__visual" aria-hidden="true">
        <img className="add-background-video-react-demo__poster" src="https://image.mux.com/601n4w1fq88NJiVpzvrQQeQfNnnjjfKMIN7dCGAEarTs/thumbnail.webp" alt="" />
        <BackgroundVideo
          ref={videoRef}
          className="add-background-video-react-demo__media"
          src="https://stream.mux.com/601n4w1fq88NJiVpzvrQQeQfNnnjjfKMIN7dCGAEarTs/highest.mp4"
          autoPlay={false}
        />
      </div>
      <div className="add-background-video-react-demo__content">
        <h3>Build the next great video experience</h3>
        <a href="#common-variations">Compare source options</a>
        <button
          type="button"
          className="add-background-video-react-demo__motion-toggle"
          onClick={() => setMotionEnabled((enabled) => !enabled)}
        >
          {motionEnabled ? 'Hide background motion' : 'Show background motion'}
        </button>
      </div>
    </section>
  );
}
```

**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,
.add-background-video-react-demo__motion-toggle {
  width: fit-content;
  padding: 0.625rem 1rem;
  color: black;
  text-decoration: none;
  font: inherit;
  cursor: pointer;
  border: 0;
  background: white;
  border-radius: 0.25rem;
}

.add-background-video-react-demo__content a:focus-visible,
.add-background-video-react-demo__motion-toggle:focus-visible {
  outline: 0.2rem solid white;
  outline-offset: 0.2rem;
}

.add-background-video-react-demo:not([data-motion-enabled]) .add-background-video-react-demo__media {
  display: none;
}

@media (prefers-reduced-motion: reduce) {
  .add-background-video-react-demo__media,
  .add-background-video-react-demo__motion-toggle {
    display: none;
  }
}
```

## How it works

BackgroundVideo renders a native `<video>` with muted, looping, inline playback. The example disables its default autoplay with `autoPlay={false}` and starts playback after checking the motion preference. The decorative wrapper contains the video and an empty-alt poster; it is hidden from assistive technology and ignores pointer input.

The page defines the hero’s size. The video fills that space with `--media-object-fit: cover`, while the poster stays behind it. The motion button pauses and hides the video, revealing the poster. It sits outside the decorative wrapper so keyboard and screen-reader users can operate it.

When `prefers-reduced-motion` is active, the script pauses playback and the CSS hides the video and motion button. CSS hiding alone does not stop playback. If the browser rejects `play()`, the example keeps the poster visible.

Set size, position, and transforms on the decorative 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.
- Provide a way to pause or hide persistent background motion. The example includes that control and follows `prefers-reduced-motion`. For the streaming variations below, stop and restart motion by mounting and unmounting the video.
- 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://videojs.org/docs/framework/react/reference/components/hls-background-video) |
| The same background-only player for a Mux HLS URL | [MuxBackgroundVideo](https://videojs.org/docs/framework/react/reference/components/mux-background-video) |

These streaming background components always autoplay. They ignore `autoPlay={false}` and `noautoplay`.

Keep the poster and motion button from the primary example. Render the streaming component only while `motionEnabled` is true, and remove the native video’s `play()`/`pause()` effect. Unmounting the component stops playback; mounting it again restarts the stream.

### 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';

<HlsBackgroundVideo
  className="hero-media"
  src="https://media.example.com/hero.m3u8"
  crossOrigin="anonymous"
  onError={() => 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';

<MuxBackgroundVideo
  className="hero-media"
  src="https://stream.mux.com/PLAYBACK_ID.m3u8?max_resolution=720p"
  crossOrigin="anonymous"
/>
```

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 `<video>` 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://videojs.org/docs/framework/react/reference/components/background-video): Decorative background video element with automatic muting and looping
- [HlsBackgroundVideo](https://videojs.org/docs/framework/react/reference/components/hls-background-video): HLS background video without controls, audio, captions, or adaptive quality
- [MuxBackgroundVideo](https://videojs.org/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://videojs.org/docs/framework/react/guides/poster): Set the image shown before playback, then add a lightweight placeholder while it loads

---

<!-- Source: https://videojs.org/docs/framework/react/guides/internationalization -->

# 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, then lazy-loads the matching locale pack. Every component label follows that locale.

```tsx
import { Container } from '@videojs/react';
import { I18nProvider } from '@videojs/react/i18n';
import { Video, VideoPlayer } from '@videojs/react/video';

export default function App() {
  return (
    <I18nProvider locale="ja">
      <VideoPlayer>
        <Container>
          <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
        </Container>
      </VideoPlayer>
    </I18nProvider>
  );
}
```

Omit `locale` to inherit a parent provider’s locale or follow the document’s `lang`. Use `langRootRef` to follow a particular DOM ancestor.

Pick a language and every label follows — no remount:

**App.tsx**

```tsx
import { createPlayer } from '@videojs/react';
import { I18nProvider } 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', 'es', 'fr', 'de', 'ja', 'ar'] as const;

type Locale = (typeof locales)[number];
const languageNames = new Intl.DisplayNames(['en'], { type: 'language' });

export default function Language() {
  const [locale, setLocale] = useState<Locale>('en');

  return (
    <div className="react-i18n-language">
      <label>
        Language
        <select value={locale} onChange={(event) => setLocale(event.currentTarget.value as Locale)}>
          {locales.map((value) => (
            <option key={value} value={value}>
              {languageNames.of(value) ?? value}
            </option>
          ))}
        </select>
      </label>
      <Player>
        <I18nProvider locale={locale}>
          <VideoSkin className="react-i18n-language__player">
            <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
          </VideoSkin>
        </I18nProvider>
      </Player>
    </div>
  );
}
```

**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 carry a translation key and an English default. The provider loads the resolved locale’s pack on demand. Locale fallback follows [BCP 47](https://www.rfc-editor.org/rfc/rfc5646) parent tags: `es-MX` checks `es`, then `en`.

The provider uses an explicit `locale` or inherits its parent provider’s locale. Otherwise it follows the document’s `lang`, with `'en'` as the fallback. To follow a particular DOM ancestor, pass `langRootRef` to [I18nProvider](https://videojs.org/docs/framework/react/reference/api/i18n-provider).

Each label uses the first available value:

1. The provider’s `translations` prop
2. The shared registry
3. The lazy-loaded locale pack
4. The component’s English default

[`registerI18n(locale, translations)`](https://videojs.org/docs/framework/react/reference/api/register-i18n) adds or replaces keys in the shared registry. Mounted providers pick up later registrations. Registering any strings for a locale prevents its pack from loading automatically. For partial global overrides, import the locale’s `/register` entry first, as shown below. This keeps the full translation available after a locale switch or provider remount.

When no shipped pack matches, the provider can use the browser’s on-device Translation API. Supply your own translations when you need reviewed wording or consistent availability across browsers.

Translate your own UI with the same machinery:

```tsx
import { useTranslator } from '@videojs/react/i18n';

function StartButton() {
  const t = useTranslator();
  return <button type="button">{t('buttons.play', { default: 'Play' })}</button>;
}
```

`default` is the English text. English ships inside component descriptors. There is no built-in `en` pack, so `t(key)` without a `default` renders the key itself under `en`. When a locale pack is active, the key selects its translation.

## 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 is in [Translation phrases](https://videojs.org/docs/framework/react/reference/api/translation-phrases). The keys are 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://videojs.org/docs/framework/react/reference/api/i18n-provider) to scope overrides to one subtree. These overrides take precedence over the registry and lazy-loaded packs:

```tsx
<I18nProvider locale="ja" translations={{ buttons: { play: '再生', pause: '一時停止' } }}>
  {/* player */}
</I18nProvider>
```

Nested providers inherit the parent locale when you only pass `translations`.

For global overrides, register the full locale pack before your custom strings:

```ts
import '@videojs/react/i18n/locales/ja/register';
import { registerI18n } from '@videojs/react/i18n';

registerI18n('ja', { buttons: { play: '再生', pause: '一時停止' } });
```

The pack supplies the remaining labels. Later calls replace only the keys you pass.

### Register your own locale

Register strings for a locale your application supports. Missing keys fall back to registered parent strings, then a shipped parent pack, then English. For example, register a few `es-MX` labels and the `es` pack supplies the rest. If the tag has its own shipped pack, registering strings for it prevents that pack from loading. Use the full-pack pattern above for that case.

```ts
import { registerI18n, type Translations } from '@videojs/react/i18n';

const esMX = {
  buttons: {
    play: 'Reproducir',
    pause: 'Pausa',
    mute: 'Silenciar',
    unmute: 'Activar sonido',
  },
} satisfies Partial<Translations>;

registerI18n('es-MX', esMX);
```

### Register a pack with the bundle

Skip lazy loading by registering a shipped locale at startup with a side-effect import. Labels render in that language on first paint:

```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';
```

Switching through the document language works only when `I18nProvider` has no explicit `locale`. To switch from React state instead:

```tsx
import { useState, type ReactNode } from 'react';
import { I18nProvider } from '@videojs/react/i18n';

export default function LocaleSwitcher({ children }: { children: ReactNode }) {
  const [locale, setLocale] = useState<'en' | 'es' | 'fr'>('en');

  return (
    <>
      <label>
        Language
        <select value={locale} onChange={(event) => setLocale(event.target.value as typeof locale)}>
          <option value="en">English</option>
          <option value="es">Español</option>
          <option value="fr">Français</option>
        </select>
      </label>
      <I18nProvider locale={locale}>{children}</I18nProvider>
    </>
  );
}
```

Wrap your player in `LocaleSwitcher`.

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, setLocale: (locale: keyof typeof loaders) => void) {
  const { default: translations } = await loaders[next]();
  registerI18n(next, translations);
  setLocale(next);
}
```

Call `switchTo(next, setLocale)` from your language picker.

### 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` you pass to that container changes only the container’s rendered attributes. Translations still come from the `I18nProvider` `locale`.

Providers without an explicit locale inherit ambient document language and direction. In that case, set `lang` and `dir` on `<html>` or another ancestor:

```html
<html lang="ar" dir="rtl">
```

In RTL layouts, playback controls keep their order and time-related media icons keep their direction. Menu motion and navigation chevrons mirror. 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';

<LiveButton>On air</LiveButton>
```

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 (`<html lang="es">`) and make translations available before first paint so labels match on server and client:

Import the pack on the server and pass it as `translations` so server-rendered labels and the first client render use the same strings. The provider can still load a locale pack on the client; the supplied strings take precedence:

```tsx
import type { ReactNode } from 'react';
import { I18nProvider } from '@videojs/react/i18n';

const loaders = {
  es: () => import('@videojs/react/i18n/locales/es'),
  fr: () => import('@videojs/react/i18n/locales/fr'),
};

export async function Player({ locale, children }: { locale: string; children: ReactNode }) {
  const load = loaders[locale as keyof typeof loaders];
  if (!load) throw new Error(`Unsupported locale: ${locale}`);
  const { default: translations } = await load();

  return (
    <I18nProvider locale={locale} translations={translations}>
      {children}
    </I18nProvider>
  );
}
```

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

Check that a provider is mounted and that its `locale`/`lang` value matches a shipped pack. Regional tags fall back to their base language, so `pt-BR` works. An unmatched language falls back to English unless the browser’s Translation API supplies translations; register your own pack for consistent coverage.

### Some strings are translated, others aren’t

If you registered partial global overrides before the locale pack loaded, the loader skips that pack. Import its `/register` entry before your overrides. For a custom locale, supply missing keys in your pack; they fall back to English until you do.

### 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://videojs.org/docs/framework/react/reference/api/i18n-provider): React provider that resolves locale and supplies a typed translator to descendants

### API

- [registerI18n](https://videojs.org/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://videojs.org/docs/framework/react/reference/api/translation-phrases): Semantic i18n keys, their English defaults, and the player UI that uses them
- [useTranslator](https://videojs.org/docs/framework/react/reference/api/use-translator): React hook that returns the typed translator for the nearest I18nProvider
- [useLocale](https://videojs.org/docs/framework/react/reference/api/use-locale): React hook that returns the active BCP 47 locale from the nearest I18nProvider
- [getI18nTranslations](https://videojs.org/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://videojs.org/docs/framework/react/guides/captions): Show captions and subtitles, and let users turn them on and pick a language.
- [Accessibility](https://videojs.org/docs/framework/react/guides/accessibility): How Video.js approaches accessibility, and what you should consider if you're deeply customizing your player

---

<!-- Source: https://videojs.org/docs/framework/react/guides/mux-data -->

# 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?utm_source=videojs&utm_campaign=vjs10&utm_content=docs-content) measures playback quality: startup time, rebuffering, playback failures, and watch time. Add the Mux Data [extension](https://videojs.org/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 (
    <Player>
      <Container>
        <MuxVideo source={{ playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM' }} playsInline />
        <MuxData />
      </Container>
    </Player>
  );
}
```

That’s the whole setup for Mux-hosted playback — no environment key required. The extension renders nothing; place it anywhere inside the player.

> **Note**
>
> Mux Data is opt-in. No media component 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, you do not need to set an environment key. The extension 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?utm_source=videojs&utm_campaign=vjs10&utm_content=docs-content):

For the hls.js example, also install `@videojs/hlsjs-video`. Replace the media and extension in the primary example with `<MonitoredHlsVideo />`:

```bash
pnpm add @videojs/hlsjs-video
```

```tsx
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
import { MuxData } from '@videojs/react/extensions/mux-data';

function MonitoredHlsVideo() {
  return (
    <>
      <HlsJsVideo src="https://example.com/stream.m3u8" />
      <MuxData envKey="YOUR_ENV_KEY" />
    </>
  );
}
```

An explicit `envKey` overrides the environment Mux infers from the playback ID. 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://videojs.org/docs/framework/react/reference/components/mux-video), [HlsJsVideo](https://videojs.org/docs/framework/react/reference/components/hlsjs-video), [DashVideo](https://videojs.org/docs/framework/react/reference/components/dash-video), and the rest alike.

How much the extension reports depends on the engine playing the stream. All media report the playback metrics available from the media element. The extension also 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 without a JavaScript engine, like native HLS or a plain `<video>`, report only the element-level metrics.

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?utm_source=videojs&utm_campaign=vjs10&utm_content=docs-content) to label views with your own titles, viewer IDs, and custom dimensions. `metadata` takes an object. In HTML, set it as a JavaScript property:

```tsx
<MuxData metadata={{ video_title: 'Big Buck Bunny', viewer_user_id: 'u_789' }} />
```

## Configuration

The [MuxData reference](https://videojs.org/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://videojs.org/docs/framework/react/reference/components/mux-data): Options for the Mux Data extension that monitors playback quality
- [MuxVideo](https://videojs.org/docs/framework/react/reference/components/mux-video): Video element for Mux-hosted HLS streams
- [MuxAudio](https://videojs.org/docs/framework/react/reference/components/mux-audio): Audio element for Mux-hosted HLS streams

### Guides

- [Cast to AirPlay and Chromecast](https://videojs.org/docs/framework/react/guides/casting): Send playback to AirPlay and Google Cast devices, with availability detection and connection state.

---

<!-- Source: https://videojs.org/docs/framework/react/guides/migrate -->

# Migrate to Video.js v10

Understand how Video.js v10 differs from the players it brings together, and choose the migration guide for the player you use today.

Video.js v10 brings together the people and lessons behind Video.js, Plyr, Vidstack, Media Chrome, and Mux Player. These projects approached web video from different directions: Video.js made HTML5 video work consistently across browsers, Plyr focused on the details of the player UI, Vidstack built for modern frameworks, Media Chrome made controls composable, and Mux Player simplified streaming integration.

Rather than merge their codebases, we rebuilt the player from scratch with what we learned from those projects. The result is one shared foundation, with native React and HTML components, customizable skins, and separate layers for player state, controls, and media playback. You can use a ready-made player or compose the pieces your application needs.

That also means v10+ is not a drop-in upgrade for any of these players. Migration involves translating your existing configuration, controls, and player API usage into the new components. Start with the guide for the player you’re using today.

## Choose your migration guide

- [Video.js 8](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8): Move from the options object, techs, plugins, and player API to v10’s composed components and player state.
- [Mux Player](https://videojs.org/docs/framework/react/guides/migrate-from-mux-player): Move from a single player element to separate player, media, and skin components.
- [Plyr](https://videojs.org/docs/framework/react/guides/migrate-from-plyr): Map your existing options, controls, and instance API to v10.
- [Media Chrome](https://videojs.org/docs/framework/react/guides/migrate-from-media-chrome): Map your controller, elements, and attributes to their v10 equivalents.
- [Vidstack](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack): Map your Vidstack player, providers, layouts, and media store onto v10’s composed components.

---

<!-- Source: https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8 -->

# 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

Move your Video.js 8 setup to v10 by replacing `videojs()` with a player, media component, and skin. This guide maps your options, techs, plugins, and imperative calls to those pieces.

Video.js 10 ships as scoped `@videojs/*` packages. The `video.js` npm package remains Video.js 8; its [repository](https://github.com/videojs/video.js) and [docs](https://legacy.videojs.org) remain available.

## Before you migrate

- List the options, techs, plugins, custom controls, and event handlers your app uses.
- Check [Known gaps](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8#known-gaps), especially ads and playlists, before replacing a working player. Plan to rewrite plugins that have no equivalent.
- Keep your existing media URLs, source formats, tracks, and required behavior. The first example uses an MP4 file. For an adaptive stream or an embed, use the matching media component.
- Choose an installation method and playback engine that fit your app and supported browsers. See [Installation](https://videojs.org/docs/guides/installation/react) and [Techs become media components](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8#techs-become-media-components).

## AI Quickstart

Paste this prompt into your coding agent:

```
Migrate this project's Video.js 8 player to Video.js v10 for React. Use @videojs/react.

Run `npx @videojs/cli agents skills` to get the Video.js skill installation instructions. Follow the printed steps for your agent. If they require a session reload, reload the session and continue with this prompt. If you can't run commands, use the installation instructions at https://github.com/videojs/skills. Use the skill throughout this migration.

Read the migration guide at https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8, including its Known gaps section. Inspect the existing player and list its media URLs, source formats, tracks, options, custom controls, event handlers, and integrations. Compare that list with the known gaps and report unsupported requirements before changing code. Keep the existing media URLs and required behavior throughout the migration.

For installation guidance, read https://videojs.org/docs/framework/react/llms.txt and follow its link to the installation guide. Keep using that online index for a CDN installation.

From the application root, run `npx @videojs/cli agents init` without flags to list installation options and their accepted values.

Choose values for these options:
- --media and --source-url: the existing content and playback requirements.
- --method: the installation method.
- --preset, --skin, and --extensions: the player UI and integrations.

Add those options to `npx @videojs/cli agents init --framework react --project existing` and run the command to print the installation plan. Follow any version-mismatch notice. Both CLI commands print instructions without changing project files. Use the printed plan to install Video.js and configure the player.

After installing a package, switch to node_modules/@videojs/react/docs/llms.txt for documentation matching its version.

Implement the migration. Then verify playback, captions, controls, and any analytics integration on every browser the project supports.
```

## 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<HTMLDivElement>(null);
  const playerRef = useRef<ReturnType<typeof videojs> | 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 <div ref={containerRef} />;
}
```

Install the React package:

```bash
npm install @videojs/react
```

Use the general video [preset](https://videojs.org/docs/framework/react/guides/presets) for on-demand content:

```tsx
'use client';

import '@videojs/react/video/skin.css';
import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';

export function MyPlayer() {
  return (
    <VideoPlayer poster="/poster.jpg">
      <VideoSkin className="app-video-player" style={{ aspectRatio: '16 / 9' }}>
        <Video src="/video.mp4" preload="auto" playsInline />
      </VideoSkin>
    </VideoPlayer>
  );
}
```

`VideoPlayer` owns the player state. Read that state with the preset’s matching [`usePlayer`](https://videojs.org/docs/framework/react/reference/api/use-player) hook. You do not manage a ref or dispose the player yourself.

Apply these changes to your existing component:

- **No `videojs()` call and no effect.** `VideoPlayer` owns the lifecycle.
- **No `controls` prop.** The skin provides the controls. Render a skin to show controls. Leave it out for a player with no UI.
- **Move the poster URL to the player.** Pass `poster` to `VideoPlayer`. The skin controls how the poster appears.

Use `'use client'` at the client boundary in frameworks with React Server Components. For a smaller control layout, replace `VideoSkin` with `NeutralVideoSkin` and import `neutral-skin.css`.

If you have chapter tracks or thumbnail tracks (`kind="metadata" label="thumbnails"`), add `default` to each track so the browser loads its cues. Keep each track’s existing `src` URL.

When enabling captions without a previous selection in this player instance, `toggleSubtitles()` prefers a track matching `navigator.language`, then falls back to the first available caption or subtitle track. For an authored track that should show on load, add `default`. See [Show captions and subtitles](https://videojs.org/docs/framework/react/guides/captions).

## Three pieces instead of one

Use these three pieces when deciding where a v8 option belongs:

**The player** provides state to descendants and renders no DOM element. Its [features](https://videojs.org/docs/framework/react/guides/features) determine the available state and actions.

**The media** plays the content and replaces the v8 tech. Choose a [media component](https://videojs.org/docs/framework/react/guides/media-sources) for your format or provider. Player controls use the capabilities that media exposes.

**The skin** supplies the controls, poster, menus, shortcuts, and gestures. Use a packaged [skin](https://videojs.org/docs/framework/react/guides/skins) as it is, or restyle it. To change its layout or interactions, install its source.

## Where your options went

Move each option to the part of your v10 setup that owns it:

1. **Media settings.** Set native attributes or props on the media.
2. **Player metadata.** The title and poster belong to player state, which lets the skin or your custom UI render them.
3. **Your CSS.** Set sizing, aspect ratio, and responsive behavior in your own CSS.
4. **Composition.** Choose components to determine which controls appear, which shortcuts run, and which language the player uses.

### Media attributes

Move native media settings onto the media component.

The React prop names in this table apply to video-backed media such as `Video` and `HlsJsVideo`. The YouTube and Vimeo components use `autoplay` instead of `autoPlay`. Their refs point to iframes. Call their media methods through `mediaRef`, which receives the playback adapter, or through `useMedia()` inside the player.

| Video.js 8 | Video.js v10 |
| --- | --- |
| `autoplay` (boolean), `playsinline`, `crossorigin` | `autoPlay`, `playsInline`, `crossOrigin` on video-backed media |
| `muted`, `loop`, `preload` | the same props on your media |
| `sources: [{ src, type }]` | `src`, or `<source>` children for progressive fallback |
| `disablePictureInPicture` | `disablePictureInPicture` on your media |

Video.js uses native autoplay. For v8’s string-valued `autoplay` options:

- `'muted'`: set both `autoplay` and `muted` on the media (`autoPlay` and `muted` on video-backed React media).
- `'play'`: to preserve v8’s explicit playback request, call `play()` on the media when it fires `loadstart` and handle rejection.
- `'any'`: on `loadstart`, call `play()` on the media. If the returned promise rejects, mute the media and call `play()` again. Implement this fallback in your app.

Keep a manual play control available if autoplay fails. See [Handle autoplay](https://videojs.org/docs/framework/react/guides/autoplay).

### Player metadata

| Video.js 8 | Video.js v10 |
| --- | --- |
| `poster` | `poster` on `VideoPlayer` |
| `posterImage: false` | set `poster=""` on the player, or remove the poster component from your local skin |
| the title in `TitleBar` | `title` on `VideoPlayer`, rendered with the Title component |

If you do not set `poster` on the player, the skin uses a poster supplied by the media, such as a generated Mux poster. Set `poster=""` to turn off this fallback.

Set a poster URL on the player for the skin to display:

```jsx
<VideoPlayer poster="/poster.jpg">
  <VideoSkin>
    <Video src="/video.mp4" />
  </VideoSkin>
</VideoPlayer>
```

The packaged video and live-video skins already include the [Title](https://videojs.org/docs/framework/react/reference/components/title) component, so setting `title` on the player displays it. Audio skins do not include a title. In a custom layout or installed skin source, add `Title` where you want the title to appear. For poster options such as placeholders and custom image elements, see [Add a poster and loading placeholder](https://videojs.org/docs/framework/react/guides/poster) and the [Poster](https://videojs.org/docs/framework/react/reference/components/poster) reference.

### Your CSS

Set sizing and aspect ratio on the skin with CSS:

| 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 container queries for the rest of your layout |

### Composition

These options need a migration decision. Each row links to the relevant guidance or identifies a gap.

| Video.js 8 | Where it lives now |
| --- | --- |
| `techOrder`, `html5.vhs.*` | [Techs become media components](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8#techs-become-media-components) |
| `children`, `controlBar: { … }` | [Customize your player](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8#customize-your-player) |
| `userActions.hotkeys`, `userActions.click`, `userActions.doubleClick` | [Customize your player](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8#customize-your-player) |
| `plugins`, `videojs.registerPlugin` | [Plugins](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8#plugins) |
| `languages`, `language`, `videojs.addLanguage` | [Languages](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8#languages) |
| `liveui`, `liveTracker` | [Live and audio-only](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8#live-and-audio-only) |
| `audioOnlyMode`, `audioPosterMode` | [Live and audio-only](https://videojs.org/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://videojs.org/docs/framework/react/guides/migrate-from-video-js-8#known-gaps) |
| `spatialNavigation` | no equivalent; see [Known gaps](https://videojs.org/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://videojs.org/docs/framework/react/reference/components/dialog); when the dialog opens or closes, your application handles any playback changes |

## Techs become media components

Choose a media component for each format or provider your v8 techs handled. Check its supported features before replacing a streaming engine.

| What you’re playing | Video.js 8 | Video.js v10 |
| --- | --- | --- |
| MP4, WebM | `techOrder: ['html5']` | a plain `<video>` |
| HLS | VHS | [hls.js video](https://videojs.org/docs/framework/react/reference/components/hlsjs-video) |
| HLS with fMP4/CMAF segments | VHS | [SPF HLS video](https://videojs.org/docs/framework/react/reference/components/hls-video), after checking its limitations |
| HLS, native only | native HLS without VHS fallback | [native HLS video](https://videojs.org/docs/framework/react/reference/components/native-hls-video) |
| DASH without DRM | VHS | [DASH video](https://videojs.org/docs/framework/react/reference/components/dash-video) |
| DASH with DRM | VHS and `videojs-contrib-eme` | [Shaka video](https://videojs.org/docs/framework/react/reference/components/shaka-video); see [DRM](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8#drm) |
| YouTube, Vimeo | a tech plugin | the YouTube and Vimeo components |
| Mux | a tech plugin | [Mux Video](https://videojs.org/docs/framework/react/reference/components/mux-video) |

`html5.vhs.overrideNative: false` lets v8 use native HLS where available while retaining VHS elsewhere. It does not mean native-only playback. Choose an HLS engine that supports your required browsers; native HLS has no fallback on browsers that cannot play the stream themselves. See [Browser support](https://videojs.org/docs/framework/react/guides/browser-support).

For an existing VHS integration, start with hls.js video and test your streams on supported browsers. This is also the component selected by the installation CLI’s `--media hls` option.

The SPF HLS component is an alternative for fMP4/CMAF streams. It does not support MPEG-TS segments, raw ADTS AAC, or whole-segment AES-128 encryption. It supports DRM through `source.drm`. Verify your license configuration and browser support with the engine you choose. See [HLS video](https://videojs.org/docs/framework/react/reference/components/hls-video) and [hls.js video](https://videojs.org/docs/framework/react/reference/components/hlsjs-video).

Each media component needs its own import. For package-manager installations, install the matching adapter package:

| Media | Package |
| --- | --- |
| hls.js video | `@videojs/hlsjs-video` |
| DASH | `@videojs/dash-video` |
| Mux video / audio | `@videojs/mux-video` / `@videojs/mux-audio` |
| YouTube | `@videojs/youtube-video` |
| Vimeo | `@videojs/vimeo-video` |
| Shaka | `@videojs/shaka-video` |
| Wistia | `@videojs/wistia-video` |

SPF and native HLS are included as dependencies of the HTML and React packages.

For hls.js video, install the adapter, import `HlsJsVideo`, and use it in place of `Video`:

```bash
npm install @videojs/react @videojs/hlsjs-video
```

```tsx
import '@videojs/react/video/skin.css';
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
import { VideoPlayer, VideoSkin } from '@videojs/react/video';

<VideoPlayer>
  <VideoSkin>
    <HlsJsVideo src="/stream.m3u8" playsInline />
  </VideoSkin>
</VideoPlayer>
```

Your VHS tuning options don’t have direct equivalents. Settings such as rendition capping and bandwidth hints are engine-specific. Configure them through the engine you chose. Video.js has no shared options object for these settings.

## Customize your player

In v8, you customized the player with options, `addChild`, component subclasses, or CSS overrides on `.vjs-*` selectors. In v10, choose a skin, restyle it with CSS custom properties, or edit its source. Try these approaches in order.

### Level 1: pick a skin

The Default skin groups settings in a menu. The Neutral skin has a compact layout like 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://videojs.org/docs/framework/react/guides/skins).

Both include AirPlay and Cast buttons. Follow [Cast to AirPlay and Chromecast](https://videojs.org/docs/framework/react/guides/casting) to add the Google Cast extension.

### Level 2: restyle it

Replace your v8 selectors with the skin’s documented custom properties where they cover the change:

```css
/* Video.js 8 */
.video-js .vjs-play-progress {
  background-color: rebeccapurple;
}
```

```css
/* The className on VideoSkin in the first example */
.app-video-player {
  --media-accent-color: rebeccapurple;
}
```

`--media-accent-color` reaches the sliders, the active buttons, and the accent surfaces at once. Video.js picks a readable text color for content on the accent color. To choose that text color yourself, set `--media-accent-text-color`. `--media-border-radius` rounds the player’s corners. `--media-scale-unit` scales the whole control bar, like v8’s `font-size` technique for sizing controls. [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin) has the full list.

### Level 3: edit skin source

To migrate `controlBar`, `addChild`, or custom component layouts, add the closest skin’s source to your project. The installed TypeScript and styles need a build step. A CDN-only page must add a build step before it can use this source. Follow [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-skin-source) for installation and file locations.

Keep the package imports for `VideoPlayer` and the media. Replace the packaged `VideoSkin` import with the installed skin component.

To remove the picture-in-picture button, remove `PiPButton` and its tooltip wrapper from the local controls layout. Keep the other controls’ contents, classes, and styles.

Move `userActions.hotkeys` customizations into the local hotkey declarations. Move click and double-click customizations into the gesture declarations. The installed skin includes both; edit those files to preserve the interactions you need.

For a control bar built from scratch, follow [UI components](https://videojs.org/docs/framework/react/guides/ui-components). Individual controls supply behavior and accessible names. You supply their visible contents, layout, and CSS.

## Plugins

v10 has no `videojs.registerPlugin`, `player.myPlugin()`, or plugin lifecycle. Audit each plugin and plan its replacement:

- **Formats and techs** (`videojs-contrib-*`, YouTube, Vimeo, Mux). Replace them with the matching [media component](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8#techs-become-media-components).
- **DRM** (`videojs-contrib-eme`, `keySystems`). Configure the media source’s license servers; see [DRM](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8#drm). Plugin callbacks and custom license requests require engine-specific migration.
- **UI additions** (extra buttons, overlays, custom control bars). Rebuild them in local skin source or with [your own component](https://videojs.org/docs/framework/react/guides/build-your-own-component).
- **Workarounds** for v8 limitations. Check whether the limitation still exists before porting the workaround.
- **Missing features** such as ads and playlists. Check [Known gaps](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8#known-gaps) before scheduling the migration. An ads-dependent player has no built-in replacement today.

### DRM

For protected DASH, use Shaka video. The dash.js component has no `source.drm` input. For protected HLS, choose an engine that supports your key systems and browsers; see [DRM protected sources](https://videojs.org/docs/framework/react/guides/media-sources#drm-protected-sources).

Move license URLs from v8’s `keySystems` configuration to `source.drm`, keyed by EME key system ID. FairPlay also needs `serverCertificateUrl` unless its CDM is pre-provisioned. Custom `getLicense` callbacks and license authentication do not transfer automatically. Reimplement them with your chosen engine’s APIs, then verify playback before you switch.

The examples configure Widevine. Replace both URL placeholders and add every key system your supported browsers need.

Install `@videojs/shaka-video` and replace the media inside your player and skin:

```tsx
import { ShakaVideo } from '@videojs/react/media/shaka-video';

<ShakaVideo
  source={{
    src: 'YOUR_DASH_MANIFEST_URL',
    drm: {
      'com.widevine.alpha': { licenseUrl: 'YOUR_WIDEVINE_LICENSE_URL' },
    },
  }}
/>
```

## Read and control the player

### Events

Your media component is a real media element, so every event you already listen for still fires on it. Keep your listeners, and attach them to the media component instead of the v8 player.

```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));
```

Map v8’s player-specific events separately:

| Video.js 8 event | Video.js v10 |
| --- | --- |
| `useractive`, `userinactive` | Read `userActive` from player state; use `controlsVisible` for whether controls are shown. |
| `texttrackchange` | Read `textTrackList` from player state. |
| `playerresize` | Observe your skin or container with `ResizeObserver`. There is no player size state. |

### 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://videojs.org/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 <span>{currentTime}</span>;
}
```

Every feature has a selector (`selectPlayback`, `selectTime`, `selectVolume`, `selectQuality`, `selectLive`, `selectTextTrack`, and so on) to read all of a feature’s state instead of a single value.

### Drive playback

Replace v8 accessor methods with [player state](https://videojs.org/docs/framework/react/reference/api/player-store) for reads. Use store actions or media properties for writes. Video.js updates player state from media events, so native calls such as `media.play()` and assignments such as `media.currentTime = 10` update the controls.

| Video.js 8 | Video.js v10 |
| --- | --- |
| `player.play()`, `player.pause()` | the player’s `play` and `pause` actions, or `media.play()` and `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.volume(0.5)` | `volume` in player state / `media.volume = 0.5` |
| `player.muted()` / `player.muted(true)` | `muted` in player state / the player’s `setMuted(true)` |
| `player.playbackRate()` / `player.playbackRate(1.5)` | `playbackRate` in player state / the player’s `setPlaybackRate(1.5)` |
| `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` |
| `player.textTracks()`, `addRemoteTextTrack()` | `<track>` elements; read `textTrackList` from player state or `textTracks` from the 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 object’s `engine` property, where one exists; get the media object with `useMedia()` |
| `videojs.getPlayer(id)` | call `usePlayer` from a component inside the player |

For video-backed media, a `ref` points to the rendered `HTMLVideoElement`. YouTube and Vimeo refs point to an `HTMLIFrameElement`. To call media methods on those embeds, pass a `mediaRef`, which receives the playback adapter, or call `useMedia()` from a component inside the player.

`useMedia()` returns the Video.js media object. If that object exposes an `engine` property, use it to access the playback engine.

Select player actions with `usePlayer`, just as you select state. For example, select `play`, `setPlaybackRate`, or `requestFullscreen`, then call the returned function.

`setVolume(value)` also unmutes when `value` is above zero. Use `media.volume = value` to preserve the current mute state. If the volume is `0`, `setMuted(false)` also sets it to `0.25`. To unmute and keep a zero volume, set `media.muted` directly.

To change sources, set `src` on the media component. If the new source needs a different playback engine, replace the media component. The UI follows the attached media.

## Languages

Video.js defaults to English and ships locale packs that load on demand. Select the locale and move `videojs.addLanguage` overrides into the i18n registry or provider. See [Internationalize the player](https://videojs.org/docs/framework/react/guides/internationalization).

To migrate `language: 'ja'`, wrap your player in [`I18nProvider`](https://videojs.org/docs/framework/react/reference/api/i18n-provider) with `locale="ja"`. To follow `<html lang>`, omit `locale`. To use a `lang` attribute on an element closer to the player, pass that element’s ref as `langRootRef`. To override individual strings, pass `translations`:

```tsx
import '@videojs/react/video/skin.css';
import { I18nProvider } from '@videojs/react/i18n';
import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';

<I18nProvider locale="en" translations={{ buttons: { play: 'Start video' } }}>
  <VideoPlayer>
    <VideoSkin>
      <Video src="/video.mp4" playsInline />
    </VideoSkin>
  </VideoPlayer>
</I18nProvider>
```

See [Internationalize the player](https://videojs.org/docs/framework/react/guides/internationalization) for scoped overrides, custom locales, and runtime switching.

## Live and audio-only

Replace `liveui` or `audioOnlyMode` with the matching live or audio [preset](https://videojs.org/docs/framework/react/guides/presets). Check its feature list when your app needs controls beyond those shown by the preset.

```tsx
import '@videojs/react/live-video/skin.css';
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
import { LiveVideoPlayer, LiveVideoSkin } from '@videojs/react/live-video';

<LiveVideoPlayer>
  <LiveVideoSkin>
    <HlsJsVideo src="/live.m3u8" playsInline />
  </LiveVideoSkin>
</LiveVideoPlayer>
```

For audio, use the audio or live audio preset. For muted video without controls, use the background video preset.

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 skins have no time slider. To preserve DVR scrubbing, add one to custom UI or installed skin source; follow [the DVR setup](https://videojs.org/docs/framework/react/guides/live-streams#dvr-let-users-scrub-back).

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.

Use [`createPlayer`](https://videojs.org/docs/framework/react/reference/api/create-player) to build a player with the features you need. Pass it a feature list, and it returns a `Player` component and a `usePlayer` hook. Every preset uses this same pair.

## Replace v8 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. v10 has no global and no public replacements, so use a platform API, a short helper of your own, or a utility library you already depend on.

| Video.js 8 | Video.js v10 |
| --- | --- |
| `videojs.time.formatTime(seconds, guide)` | The [Time](https://videojs.org/docs/framework/react/reference/components/time) component for an on-screen time display. For a string of your own, a few lines of arithmetic (below), or `Intl.DurationFormat` in browsers that support it |
| `videojs.fn.throttle(fn, wait)` | Your own helper, or `throttle` from a utility library such as lodash |
| `videojs.dom.isEl(value)` and its type-specific cousins | `instanceof` checks such as `value instanceof Element`, `value instanceof HTMLMediaElement`, or `value instanceof HTMLVideoElement` |
| `videojs.obj.merge(a, b)` | Object spread (`{ ...a, ...b }`) for a shallow merge, or `merge({}, a, b)` from a utility library such as lodash for a deep one. Pass the empty object first, because lodash’s `merge` mutates its first argument |

For example, a clock-style string such as `1:05` or `1:02:03`:

```js
function formatTime(seconds) {
  if (!Number.isFinite(seconds)) return '0:00';

  const total = Math.floor(Math.abs(seconds));
  const h = Math.floor(total / 3600);
  const m = Math.floor(total / 60) % 60;
  const s = String(total % 60).padStart(2, '0');
  const time = h > 0 ? `${h}:${String(m).padStart(2, '0')}:${s}` : `${m}:${s}`;

  return seconds < 0 ? `-${time}` : time;
}
```

## Known gaps

Check these limitations against your required features:

- **No ads support.** v8’s IMA and ad-plugin ecosystem has no v10 equivalent. If your player depends on ads, resolve that requirement before replacing it.
- **No playlist support.** No `videojs-playlist` equivalent.
- **No plugin system**, by design. Budget for rebuilding UI plugins as components. See [Plugins](https://videojs.org/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 equivalent to v8’s `textTrackSettings`. You can still style browser-rendered cues with `::cue`; see [Show captions and subtitles](https://videojs.org/docs/framework/react/guides/captions).
- No spatial navigation. v8’s `spatialNavigation` for TV and D-pad remotes has no equivalent.
- Player preferences such as volume, captions language, speed, and quality are not persisted automatically ([#944](https://github.com/videojs/v10/issues/944)). For application-managed persistence, follow [Remember user preferences](https://videojs.org/docs/framework/react/guides/user-preferences).
- No VHS-equivalent tuning surface. Engine settings belong to the engine you chose, and the SPF HLS component deliberately exposes few of them.
- Chapters render in the time slider from a default `<track kind="chapters">`, 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)). For `inactivityTimeout: 0`, set `visibility="always"` on the controls component in a custom layout or installed skin source.
- No full-window fullscreen fallback. Test fullscreen on your supported browsers; see [Browser support](https://videojs.org/docs/framework/react/guides/browser-support).
- Multiple `<source>` elements with `size` metadata don’t become a quality menu. Use HLS or DASH for adaptive quality.
- The Default, Neutral, and Compat skins are available. Runtime theme switching is not supported.
- Native controls are not automatically removed when custom controls load ([#1160](https://github.com/videojs/v10/issues/1160)).
- Debug mode has no equivalent yet ([#1406](https://github.com/videojs/v10/issues/1406)).

## See also

- [Features](https://videojs.org/docs/framework/react/guides/features) and [Presets](https://videojs.org/docs/framework/react/guides/presets)
- [Media sources](https://videojs.org/docs/framework/react/guides/media-sources)
- [Skins](https://videojs.org/docs/framework/react/guides/skins) and [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins)

---

<!-- Source: https://videojs.org/docs/framework/react/guides/migrate-from-mux-player -->

# Migrate from Mux Player

Move a Mux Player embed to Video.js v10 using a player, media component, skin, and analytics extension

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://videojs.org/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://videojs.org/docs/framework/react/guides/background-video). It starts with a browser-playable video file, then covers the HLS and Mux background components.

## AI Quickstart

Paste this prompt into your coding agent:

```
Migrate this project's Mux Player player to Video.js v10 for React. Use @videojs/react.

Run `npx @videojs/cli agents skills` to get the Video.js skill installation instructions. Follow the printed steps for your agent. If they require a session reload, reload the session and continue with this prompt. If you can't run commands, use the installation instructions at https://github.com/videojs/skills. Use the skill throughout this migration.

Read the migration guide at https://videojs.org/docs/framework/react/guides/migrate-from-mux-player, including its Known gaps section. Inspect the existing player and list its media URLs, source formats, tracks, options, custom controls, event handlers, and integrations. Compare that list with the known gaps and report unsupported requirements before changing code. Keep the existing media URLs and required behavior throughout the migration.

For installation guidance, read https://videojs.org/docs/framework/react/llms.txt and follow its link to the installation guide. Keep using that online index for a CDN installation.

From the application root, run `npx @videojs/cli agents init` without flags to list installation options and their accepted values.

Choose values for these options:
- --media and --source-url: the existing content and playback requirements.
- --method: the installation method.
- --preset, --skin, and --extensions: the player UI and integrations.

Add those options to `npx @videojs/cli agents init --framework react --project existing` and run the command to print the installation plan. Follow any version-mismatch notice. Both CLI commands print instructions without changing project files. Use the printed plan to install Video.js and configure the player.

After installing a package, switch to node_modules/@videojs/react/docs/llms.txt for documentation matching its version.

Implement the migration. Then verify playback, captions, controls, and any analytics integration on every browser the project supports.
```

## Before you migrate

Make a migration checklist before changing your embed:

- **List the Mux Player attributes or React props you set.** Compare them with the mapping tables below.
- **Grep your codebase for `mux-player` selectors.** After the swap, CSS rules and `querySelector` calls that reach into the element stop matching, with no error. Look for patterns such as `mux-player::part(…)`, `mux-player [role="slider"]`, and `player.shadowRoot`. Restyle the UI with the skin’s custom properties or rebuild it with Video.js components.
- **Find your event listeners and imperative calls** (`play()`, `currentTime`, `addChapters`). Media APIs move to the media component; the rest is mapped under [Drive playback](https://videojs.org/docs/framework/react/guides/migrate-from-mux-player#drive-playback).
- **Note your theme and CSS variables.** Compare your Mux Player theme with the two Video.js skins, and map its CSS variables.
- **Check [Known gaps](https://videojs.org/docs/framework/react/guides/migrate-from-mux-player#known-gaps)** for features your app needs.
- **Check your catalog for MPEG-TS, raw ADTS AAC, AES-128, low-latency HLS, or DVR streams.** Check whether the SPF engine supports these requirements. If you use DRM, verify playback with whichever engine you choose. See [Which Mux media should you use?](https://videojs.org/docs/framework/react/guides/migrate-from-mux-player#which-mux-media-should-you-use).

## Your first player

The examples keep a playback ID, analytics metadata, and a poster from two seconds into the video. Replace `YOUR_PLAYBACK_ID` with your existing playback ID before running them.

```tsx
import MuxPlayer from '@mux/mux-player-react';

export function MyPlayer() {
  return (
    <MuxPlayer
      playbackId="YOUR_PLAYBACK_ID"
      metadata={{ video_title: 'Test VOD', viewer_user_id: 'user-id-007' }}
      thumbnailTime={2}
    />
  );
}
```

`@videojs/react` provides native React components for the player, media, skin, and extensions.

```bash
npm install @videojs/react @videojs/mux-video @videojs/mux-data
```

Start with the general-purpose `@videojs/react/video` [preset](https://videojs.org/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 title="Test VOD">
      <VideoSkin style={{ aspectRatio: '16 / 9' }}>
        <MuxVideo
          source={{ playbackId: 'YOUR_PLAYBACK_ID', poster: { time: 2 } }}
          playsInline
          crossOrigin="anonymous"
        />
        <MuxData
          metadata={{ video_title: 'Test VOD', viewer_user_id: 'user-id-007' }}
        />
      </VideoSkin>
    </VideoPlayer>
  );
}
```

`VideoPlayer` is the piece that owns the state. To read that state, the preset ships a matching [`usePlayer`](https://videojs.org/docs/framework/react/reference/api/use-player) hook.

Use `'use client'` at the client boundary in frameworks with React Server Components.

> **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 the extension to preserve Mux Player’s monitoring. Leave it out only if you intend to stop monitoring.

Preserve these behaviors when adapting the example:

- **The skin has no size of its own**, so the examples give it one with an inline `aspect-ratio`. Any CSS that sizes the skin works, such as your own class or a Tailwind utility like `aspect-video`. See [Move your layout styles](https://videojs.org/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.
- **Thumbnail previews come from the Mux media.** 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://videojs.org/docs/framework/react/guides/mux-data).
- **Chromecast is opt-in.** To add Chromecast, follow [Cast to AirPlay and Chromecast](https://videojs.org/docs/framework/react/guides/casting). Otherwise, leave the Google Cast extension out.

### 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 the skin and stack inside it. `VideoPlayer` renders no DOM element of its own.

If you leave out `VideoSkin` to build your own UI, add a [`Container`](https://videojs.org/docs/framework/react/reference/components/player-container). Style and measure that element, and put overlays inside it:

```tsx
import { Container } from '@videojs/react';
import { MuxVideo } from '@videojs/react/media/mux-video';
import { VideoPlayer } from '@videojs/react/video';

<VideoPlayer>
  <Container style={{ position: 'relative', width: '100%', aspectRatio: '16/9' }}>
    <MuxVideo source={{ playbackId: 'YOUR_PLAYBACK_ID' }} />
    <div style={{ position: 'absolute', inset: 0, pointerEvents: 'none' }}>Your overlay</div>
  </Container>
</VideoPlayer>
```

> **Note**
>
> Put standard media handlers such as `onPlay`, `onTimeUpdate`, `onEnded`, and `onError` on `MuxVideo`. Use [`usePlayer`](https://videojs.org/docs/framework/react/reference/api/use-player) for player-store state. See [Read and control the player](https://videojs.org/docs/framework/react/guides/migrate-from-mux-player#read-and-control-the-player).

The examples leave out the player software name and version. If your app already sets them, copy them to the Mux Data extension. Use `player-software-name` and `player-software-version` in HTML, or `playerSoftwareName` and `playerSoftwareVersion` in React. Preserve your existing Mux Data metadata as well.

## Three pieces instead of one

Use these three pieces when deciding where each Mux Player setting belongs:

**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://videojs.org/docs/framework/react/guides/features) it’s built from.

**The media** is the thing that plays the video. Use Mux media for Mux playback IDs and source settings. Choose another [media component](https://videojs.org/docs/framework/react/guides/media-sources) when changing providers, and check which capabilities it exposes.

**The skin** is the UI: the controls, the poster, the captions, the settings menu, the keyboard shortcuts. [Skins](https://videojs.org/docs/framework/react/guides/skins) are pre-built arrangements of smaller components, and you can use one as-is, restyle it, or add its source to your project and edit it.

## Autoplay

Video.js uses native autoplay. Move Mux Player’s boolean autoplay setting to the media. For its string-valued modes:

- `muted`: set both `autoplay` and `muted` on the media (`autoPlay` and `muted` in React).
- `any`: on `loadstart`, call `play()` on the media. If the returned promise rejects, mute the media and call `play()` again. Implement this fallback in your app.

Keep a manual play control available if autoplay fails. See [Handle autoplay](https://videojs.org/docs/framework/react/guides/autoplay).

## 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: 'YOUR_PLAYBACK_ID',
  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
<MuxVideo source={{ playbackId: 'YOUR_PLAYBACK_ID' }} />
```

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
<MuxVideo src="https://stream.mux.com/YOUR_PLAYBACK_ID.m3u8?max_resolution=1080p" />
```

`MuxVideo` has no `playbackId` prop. Set `source.playbackId`.

Here’s where the Mux Player React props land. Mux Player groups signing tokens in `tokens`; Video.js puts each token in the source group for 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 put resolution caps and clipping in the token itself.

## Analytics moves to its own extension

Render the [Mux Data extension](https://videojs.org/docs/framework/react/reference/components/mux-data) inside the player, and move Mux Player’s analytics settings to its props.

| 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.

Mux media loads the asset’s title from its metadata. If you omit the display title on the player, the player uses the title set in the Mux dashboard.

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://videojs.org/docs/framework/react/reference/components/title#styling) component sets `data-visible` while the controls are visible, so your skin overrides can style the title differently when the controls show or hide. The audio skins have no title display.

In installed skin source or a custom layout, the title appears where you place the title component. Put the title component inside the sized container from [Move your layout styles](https://videojs.org/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';

<VideoPlayer title="Test VOD">
  <Container style={{ position: 'relative', width: '100%', aspectRatio: '16/9' }}>
    <MuxVideo source={{ playbackId: 'YOUR_PLAYBACK_ID' }} />
    <Title />
  </Container>
</VideoPlayer>
```

`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.

To show a placeholder while the generated poster loads:

```jsx
<VideoPlayer>
  <VideoSkin
    renderPoster={
      <img
        alt=""
        style={{ background: "url('/placeholder.webp') center / contain no-repeat" }}
      />
    }
  >
    <MuxVideo source={{ playbackId: 'YOUR_PLAYBACK_ID' }} />
  </VideoSkin>
</VideoPlayer>
```

`renderPoster` customizes the image while preserving the poster URL from the Mux source, including any thumbnail token. Replace `/placeholder.webp` with your existing placeholder image URL or data URL to show it while the full poster loads.

Mux serves poster images from its `thumbnail` endpoint. Configure the image URL with `source.poster`. Move Mux Player’s `thumbnailTime` value to `source.poster.time`. Set `width`, `height`, `fitMode`, `rotate`, and `ext` on `source.poster` to control image size, cropping, rotation, and format. Video.js converts those camel-case keys to the `snake_case` query parameters Mux expects. See [Add a poster and loading placeholder](https://videojs.org/docs/framework/react/guides/poster) for more examples or the [Poster](https://videojs.org/docs/framework/react/reference/components/poster) reference for the component itself.

## Customize your player

Choose the smallest customization that meets your existing UI requirements: a packaged skin, its CSS variables, or editable skin source.

### Level 1: pick a skin

Video.js has three packaged skins. The Default skin groups settings in a menu. The Neutral skin has a compact layout like a classic player control bar. The Compat skin uses plain surfaces and basic controls for broader browser support. All three 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://videojs.org/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
<VideoSkin className="my-player-skin">...</VideoSkin>
```

```css
.my-player-skin {
  --media-accent-color: rebeccapurple;
}
```

`--media-accent-color` reaches the sliders, the active buttons, and the accent surfaces. Video.js picks a readable text color for content on the accent color. To choose that text color yourself, set `--media-accent-text-color`. `--media-border-radius` rounds the player’s corners. `--media-scale-unit` scales the whole control bar. [Customize skins](https://videojs.org/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 direct replacements for Mux Player’s primary and secondary colors. 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 TypeScript components and styles become local files that need a build step. A CDN-only page must add a build step before it can use this source. [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-skin-source) covers the setup and available skins.

To migrate `forwardSeekOffset` and `backwardSeekOffset`, edit the installed skin’s hotkey and gesture declarations.

Replace the existing seek declarations, including the `j` and `l` shortcuts, with ones that use your offsets. These examples use 30 seconds forward and backward:

```tsx
import { Gesture, Hotkey } from '@videojs/react';

<>
  <Hotkey keys="ArrowRight" action="seekStep" value={30} />
  <Hotkey keys="ArrowLeft" action="seekStep" value={-30} />
  <Hotkey keys="l" action="seekStep" value={30} />
  <Hotkey keys="j" action="seekStep" value={-30} />
  <Gesture type="doubletap" action="seekStep" value={30} region="right" />
  <Gesture type="doubletap" action="seekStep" value={-30} region="left" />
</>
```

Neither packaged video skin includes skip buttons. To keep those controls from Mux Player, add a [seek button](https://videojs.org/docs/framework/react/reference/components/seek-button), which takes `seconds` and defaults to 30.

To remove a control, remove it and its tooltip wrapper from the local controls layout.

## Read and control the player

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://videojs.org/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 <span>{currentTime}</span>;
}
```

Every feature has a selector (`selectPlayback`, `selectTime`, `selectVolume`, `selectQuality`, `selectLive`, `selectTextTrack`, and so on) to read all of a feature’s state instead of a single value.

Call `usePlayer` from a descendant of `VideoPlayer`. Move `VideoPlayer` above any components that need its state. It renders no DOM element, so this does not add a layout wrapper.

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

Use the [player store](https://videojs.org/docs/framework/react/reference/api/player-store) for state and actions:

| Mux Player | Video.js v10 |
| --- | --- |
| `player.play()`, `player.pause()` | the player’s `play` and `pause` actions, or `media.play()` and `media.pause()` |
| `player.currentTime = 10` | the player’s `seek(10)`, or `media.currentTime = 10` |
| `player.volume` | Read `volume` from player state. Write it with `setVolume(value)`, which also unmutes for values above zero, or with `media.volume = value` to keep the mute state. |
| `player.muted` | `muted` in player state; write with `setMuted(value)` |
| `player.playbackRate` | the player’s `setPlaybackRate`, or `media.playbackRate` |
| `player.requestFullscreen()` | the player’s `requestFullscreen`, `exitFullscreen` |
| `player.addChapters([…])` | a `<track kind="chapters">`, covered below |

Standard media properties update player state through media events. If the volume is `0`, `setMuted(false)` also sets it to `0.25`. Mux Player’s smart-unmute behavior carries over through `setMuted(false)`. To unmute and keep a zero volume, set `media.muted` directly.

Select actions with `usePlayer` in a descendant of `VideoPlayer` and call them from your UI:

```tsx
import { usePlayer } from '@videojs/react/video';

function SeekToTen() {
  const seek = usePlayer((state) => state.seek);
  return <button type="button" onClick={() => seek(10)}>Seek to 10 seconds</button>;
}
```

Store actions throw until the media attaches. Call fullscreen actions from a user interaction, such as a click handler.

## Which Mux media should you use?

Choose and test the engine before migration, especially when your catalog uses DRM or TS-packaged media.

`MuxVideo` supports two playback engines: SPF and hls.js. Choose the engine by import path. The `/spf` import is smaller, and `/hls-js` is more compatible. The default import currently uses hls.js. Start with that default:

| Import | Engine | When |
| --- | --- | --- |
| `.../media/mux-video` | hls.js | **The default. Start here.** |
| `.../media/mux-video/spf` | SPF | Your streams use fMP4/CMAF segments and fit the limitations below. |
| `.../media/mux-video/hls-js` | hls.js | Your app depends on hls.js and needs its instance or settings. |

The SPF engine does not support MPEG-TS segments, raw ADTS AAC, or whole-segment AES-128 encryption. Keep the default for assets that need those formats. The SPF engine also lacks low-latency HLS support, and its DVR playback is experimental.

Both flavors support DRM through `source.drm`. Verify license exchange and playback with your protected assets on supported browsers before changing engines.

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 import currently uses hls.js, but its engine can change in a future release. Use `/hls-js` when your app depends on hls.js APIs. Test the chosen engine with your assets and supported browsers.

The Mux audio component has the same three import paths. Use it with the audio player and audio skins.

## Live streams

Mux Player switches to live controls automatically. In Video.js, choose the live preset yourself.

```tsx
import '@videojs/react/live-video/skin.css';
import { LiveVideoPlayer, LiveVideoSkin } from '@videojs/react/live-video';
import { MuxVideo } from '@videojs/react/media/mux-video';

<LiveVideoPlayer>
  <LiveVideoSkin>
    <MuxVideo source={{ playbackId: 'YOUR_PLAYBACK_ID' }} playsInline />
  </LiveVideoSkin>
</LiveVideoPlayer>
```

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 reads the stream type from 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://videojs.org/docs/framework/react/reference/api/feature-live).

The live skins have no time slider. To preserve DVR scrubbing, add one to custom UI or installed skin source; follow [the DVR setup](https://videojs.org/docs/framework/react/guides/live-streams#dvr-let-users-scrub-back).

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://videojs.org/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';

<LiveButton className="station-live-button">On air</LiveButton>
```

Do not rebuild this behavior by reading `duration` or by setting `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://videojs.org/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://videojs.org/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

The video skins include a settings menu with the available quality, audio-track, captions, and playback-rate controls:

| What | Component | Notes |
| --- | --- | --- |
| Quality | [Quality radio group](https://videojs.org/docs/framework/react/reference/components/quality-radio-group) | Lets a viewer pick the video quality. Use `source.playback.maxResolution` to cap the stream’s available resolution; it does not force playback at that resolution. |
| Audio tracks | [Audio track radio group](https://videojs.org/docs/framework/react/reference/components/audio-track-radio-group) | For multi-language audio. |
| Captions | [Captions radio group](https://videojs.org/docs/framework/react/reference/components/captions-radio-group) | Rendered by the browser. |
| Speed | [Playback rate radio group](https://videojs.org/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)). |

When enabling captions without a previous selection in this player instance, `toggleSubtitles()` prefers a track matching `navigator.language`, then falls back to the first available caption or subtitle track. For an authored track that should show on load, add `default`. See [Show captions and subtitles](https://videojs.org/docs/framework/react/guides/captions).

Video.js has no viewer-facing text-track settings dialog. You can style browser-rendered captions with `::cue`.

## Chapters and cue points

Add a chapters track with the `default` attribute inside your media. The skins then split the [time slider](https://videojs.org/docs/framework/react/reference/components/time-slider) into chapter segments and show the chapter title on hover:

```jsx
<MuxVideo source={{ playbackId: 'YOUR_PLAYBACK_ID' }}>
  <track kind="chapters" src="/chapters.vtt" default />
</MuxVideo>
```

To replace `addChapters()`, convert your chapter array to a WebVTT file and set its URL as the track’s `src` ([#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

For signed playback, follow Mux’s [secure video playback guide](https://www.mux.com/docs/guides/secure-video-playback?utm_source=videojs&utm_campaign=vjs10&utm_content=docs-content) to create a signing key and generate tokens on your server. In the example below, replace `YOUR_PLAYBACK_ID` with the signed asset’s playback ID. Replace each token placeholder with the matching server-generated token. Each token goes in its own group.

Video.js checks the audience of poster, storyboard, and DRM tokens before building their URLs. It passes playback tokens through for Mux to validate. A misplaced playback token still produces a stream request that Mux rejects:

```js
{
  playbackId: 'YOUR_PLAYBACK_ID',
  playback: { token: 'PLAYBACK_TOKEN' },   // audience: v
  poster: { token: 'THUMBNAIL_TOKEN' },     // audience: t
  storyboard: { token: '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 detects an expired token and shows a message. Video.js does not report expired tokens yet ([#1432](https://github.com/videojs/v10/issues/1432)).

For DRM on either Mux media flavor, supply a license token. Video.js derives the FairPlay, Widevine, and PlayReady license servers and the FairPlay application certificate:

```js
{
  playbackId: 'YOUR_PLAYBACK_ID',
  playback: { token: 'PLAYBACK_TOKEN' },
  drm: { token: 'DRM_TOKEN' }, // audience: d
}
```

DRM playback is always signed, so set both `source.drm.token` and `source.playback.token`. For content Mux does not license, add your own license servers to `source.drm`, keyed by key system. For each key system you configure, your server replaces the derived server.

The SPF flavor supports FairPlay, Widevine, and PlayReady through its EME license pipeline. DRM availability still depends on the browser, key system, and asset configuration.

## 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 | `mediaRef.current` from a `mediaRef` on the media component, or `useMedia()` inside the player |
| the hls.js instance | the media object’s `.engine` on the hls.js-backed flavor |
| `prefer-playback` | `source.preferPlayback`, or pick [native HLS](https://videojs.org/docs/framework/react/reference/components/native-hls-video) outright |

`source.preferPlayback` is the closest mapping. To match `prefer-playback="native"`, set it to `'native'`. The Mux media then uses the browser’s built-in HLS support instead of building an MSE pipeline.

> **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`. Pass a `mediaRef` to the media component, or call `useMedia()` inside the player, to get 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.

Video.js has no Program Date Time (PDT) helpers such as `getStartDate()` or `currentPdt`. The player exposes `liveEdgeStart` and `targetLiveWindow`. To read PDT, use the playback engine.

## Known gaps

Check these limitations against your required features:

- The two packaged skins do not reproduce Mux Player’s themes, and there is no runtime theme switch. Plan skin customization when preserving a theme such as `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)). For always-visible controls, set `visibility="always"` on the controls component in a custom layout or installed skin source.
- Player preferences such as volume, captions language, speed, and quality are not persisted automatically ([#944](https://github.com/videojs/v10/issues/944)). Mux users can set `source.playback.defaultSubtitlesLang` so the HLS playlist sets the default subtitle language. For application-managed persistence, follow [Remember user preferences](https://videojs.org/docs/framework/react/guides/user-preferences).
- Debug mode has no equivalent yet ([#1406](https://github.com/videojs/v10/issues/1406)).

## See also

- [Mux Video](https://videojs.org/docs/framework/react/reference/components/mux-video) and [Mux Audio](https://videojs.org/docs/framework/react/reference/components/mux-audio)
- [Mux Data](https://videojs.org/docs/framework/react/guides/mux-data)
- [Skins](https://videojs.org/docs/framework/react/guides/skins) and [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins)

---

<!-- Source: https://videojs.org/docs/framework/react/guides/migrate-from-plyr -->

# Migrate from Plyr

Move an existing Plyr integration to Video.js v10, mapping Plyr options and its instance API onto components and player state

Replace Plyr’s constructor and options object with a Video.js player, media component, and skin. Read playback and UI state through [player state](https://videojs.org/docs/framework/react/guides/features).

Start with the Neutral skin, move media settings into markup, and replace calls to the Plyr instance with native media APIs or Video.js store actions.

## AI Quickstart

Paste this prompt into your coding agent:

```
Migrate this project's Plyr player to Video.js v10 for React. Use @videojs/react.

Run `npx @videojs/cli agents skills` to get the Video.js skill installation instructions. Follow the printed steps for your agent. If they require a session reload, reload the session and continue with this prompt. If you can't run commands, use the installation instructions at https://github.com/videojs/skills. Use the skill throughout this migration.

Read the migration guide at https://videojs.org/docs/framework/react/guides/migrate-from-plyr, including its Known gaps section. Inspect the existing player and list its media URLs, source formats, tracks, options, custom controls, event handlers, and integrations. Compare that list with the known gaps and report unsupported requirements before changing code. Keep the existing media URLs and required behavior throughout the migration.

For installation guidance, read https://videojs.org/docs/framework/react/llms.txt and follow its link to the installation guide. Keep using that online index for a CDN installation.

From the application root, run `npx @videojs/cli agents init` without flags to list installation options and their accepted values.

Choose values for these options:
- --media and --source-url: the existing content and playback requirements.
- --method: the installation method.
- --preset, --skin, and --extensions: the player UI and integrations.

Add those options to `npx @videojs/cli agents init --framework react --project existing` and run the command to print the installation plan. Follow any version-mismatch notice. Both CLI commands print instructions without changing project files. Use the printed plan to install Video.js and configure the player.

After installing a package, switch to node_modules/@videojs/react/docs/llms.txt for documentation matching its version.

Implement the migration. Then verify playback, captions, controls, and any analytics integration on every browser the project supports.
```

## What changes

- **Player, media, and skin are separate.** Put source settings on the media, poster metadata on the player, and controls in the skin.
- **HLS and DASH need a streaming media component.** Keep the playback engine your app requires; see [Streaming](https://videojs.org/docs/framework/react/guides/migrate-from-plyr#streaming).
- **Controls are composed in a skin.** To migrate Plyr’s `controls`, hotkeys, or gestures, [edit skin source](https://videojs.org/docs/framework/react/guides/migrate-from-plyr#edit-skin-source).
- **Casting needs setup.** The video skins include AirPlay and Cast buttons. The Cast button needs the Google Cast extension. Follow [Cast to AirPlay and Chromecast](https://videojs.org/docs/framework/react/guides/casting).

Use `@videojs/react` components and hooks to replace the Plyr constructor and disposal effect.

> **Note**
>
> Check [Known gaps](https://videojs.org/docs/framework/react/guides/migrate-from-plyr#known-gaps) before replacing your player, especially if your app uses ads, persisted preferences, source-based quality selection, or fullscreen fallback. Keep your existing media URLs and track files when adapting the examples.

## Basic migration

Start with a Plyr player that has captions, thumbnail previews, and a poster:

```html
<link rel="stylesheet" href="path/to/plyr.css" />

<video id="player" src="/path/to/video.mp4" playsinline controls data-poster="/path/to/poster.jpg">
  <track kind="captions" label="English" src="/path/to/captions/en.vtt" srclang="en" default />
</video>

<script src="https://cdn.plyr.io/3.8.4/plyr.js"></script>

<script>
const player = new Plyr('#player', {
  previewThumbnails: {
    enabled: true,
    src: '/path/to/storyboard.vtt',
  },
});
</script>
```

The Neutral 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/neutral-skin.css';
import { NeutralVideoSkin, Video, VideoPlayer } from '@videojs/react/video';

export function AppVideoPlayer() {
  return (
    <VideoPlayer poster="/path/to/poster.jpg">
      <NeutralVideoSkin className="app-video-player" style={{ aspectRatio: '16 / 9' }}>
        <Video src="/path/to/video.mp4" playsInline>
          <track kind="captions" label="English" src="/path/to/captions/en.vtt" srcLang="en" default />
          <track kind="metadata" label="thumbnails" src="/path/to/storyboard.vtt" default />
        </Video>
      </NeutralVideoSkin>
    </VideoPlayer>
  );
}
```

### Notes

- `@videojs/react/video` is a [preset](https://videojs.org/docs/framework/react/guides/presets): a player, a skin, and a media component that already fit together. `VideoPlayer` owns the player state and uses the standard set of [features](https://videojs.org/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://videojs.org/docs/framework/react/guides/poster).
- To use the Default skin, import `skin.css` and replace `NeutralVideoSkin` with `VideoSkin` in the import and JSX.

If caption or thumbnail tracks come from a different origin than the page, set `crossorigin="anonymous"` on the media (`crossOrigin="anonymous"` in React). Also serve the media and track files with CORS headers that allow your page’s origin. See [Thumbnail](https://videojs.org/docs/framework/react/reference/components/thumbnail).

## Map common features

### Streaming

For HLS or DASH, replace the native video component with a [media component](https://videojs.org/docs/framework/react/guides/media-sources) for that format. Check that the component’s engine supports your stream before you choose it.

#### HLS

If your Plyr integration uses hls.js, keep it by using the hls.js video component. The installation CLI’s `--media hls` option selects this component.

The SPF [HLS video](https://videojs.org/docs/framework/react/reference/components/hls-video) component is an alternative for fMP4/CMAF streams. It does not support MPEG-TS segments, raw ADTS AAC, or whole-segment AES-128 encryption. It supports DRM through `source.drm`. Verify your license configuration and browser support with the engine you choose before switching.

Install the adapter, import `HlsJsVideo`, and use it in place of `Video`:

```bash
npm install @videojs/react @videojs/hlsjs-video
```

```js
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
```

Set `src` to your `.m3u8` manifest URL.

#### DASH

Use the DASH media component for an unprotected DASH source. For DRM-protected DASH, use [Shaka video](https://videojs.org/docs/framework/react/reference/components/shaka-video) and configure `source.drm`; the dash.js component has no DRM configuration input. See [the DRM migration example](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8#drm).

Install the adapter, import `DashVideo`, and use it in place of `Video`:

```bash
npm install @videojs/react @videojs/dash-video
```

```js
import { DashVideo } from '@videojs/react/media/dash-video';
```

Set `src` to your `.mpd` manifest URL.

### Vimeo

Use the Vimeo media component for your existing Vimeo source.

Install the adapter, import `VimeoVideo`, and use it in place of `Video`:

```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

Use the YouTube media component for your existing YouTube source.

Install the adapter, import `YouTubeVideo`, and use it in place of `Video`:

```bash
npm install @videojs/react @videojs/youtube-video
```

```js
import { YouTubeVideo } from '@videojs/react/media/youtube-video';
```

```jsx
<VideoPlayer>
  <NeutralVideoSkin>
    <YouTubeVideo src="https://youtu.be/aqz-KE-bpKQ" playsInline />
  </NeutralVideoSkin>
</VideoPlayer>
```

The component accepts YouTube watch, `youtu.be` short-link, embed, Shorts, live, playlist, and privacy-enhanced (`youtube-nocookie.com`) URLs, as well as raw 11-character video IDs.

### Internationalization

Video.js defaults to English. To migrate Plyr’s `i18n` strings, register translation overrides or pass them to a provider. For shipped locales and language selection, follow [Internationalize the player](https://videojs.org/docs/framework/react/guides/internationalization).

Wrap the skin in `I18nProvider` to select a locale and scope string overrides. The example overrides English; set `locale` to the language your app uses:

```tsx
'use client';

import '@videojs/react/video/neutral-skin.css';
import { I18nProvider } from '@videojs/react/i18n';
import { NeutralVideoSkin, Video, VideoPlayer } from '@videojs/react/video';

export function MyPlayer() {
  return (
    <VideoPlayer>
      <I18nProvider
        locale="en"
        translations={{
          buttons: {
            play: 'Start video',
            pause: 'Pause video',
          },
          menu: {
            settings: 'Options',
          },
        }}
      >
        <NeutralVideoSkin>
          <Video src="/video.mp4" playsInline />
        </NeutralVideoSkin>
      </I18nProvider>
    </VideoPlayer>
  );
}
```

## Configuration

Move media options to attributes or props. For controls and interactions, use a skin or [edit its installed source](https://videojs.org/docs/framework/react/guides/migrate-from-plyr#edit-skin-source). Where the table says to edit local skin source, it means those installed files:

| Plyr option | Video.js v10 |
| --- | --- |
| `controls` | Choose a [skin](https://videojs.org/docs/framework/react/guides/skins) with the controls you need, or edit local skin source. Video skins do not include `rewind` or `fast-forward` buttons. |
| `rewind`, `fast-forward`, `seekTime` | The audio skins include 10-second skip buttons; the video skins do not. In local skin source, add a [seek button](https://videojs.org/docs/framework/react/reference/components/seek-button), which skips by its `seconds` value (default `30`; negative values seek backward). |
| `settings` | The skins show a settings menu automatically when quality, speed, audio tracks, or captions are available. |
| `autoplay`, `muted`, `loop`, `playsinline`, `preload` | Set these on the media. For video-backed React media, use `autoPlay` and `playsInline`; the other names stay the same. YouTube and Vimeo use `autoplay`. |
| `poster` / `data-poster` | Set `poster` on the player. See [Basic migration](https://videojs.org/docs/framework/react/guides/migrate-from-plyr#basic-migration). |
| `ratio` | Set `aspect-ratio` in CSS on the skin component. |
| `hideControls` | Preset skins hide controls after inactivity. For `hideControls: false`, set `visibility="always"` on the controls component in a custom layout or installed skin source. The hide delay is not configurable yet. |
| `clickToPlay` | Preset video skins include click and tap gestures. Edit local skin source to remove or change them. |
| `keyboard` | Preset video skins include common hotkeys. Edit local skin source to remove or change them. For `keyboard.global: true`, set `target="document"` on the hotkey components. |
| `tooltips` | Preset skins include tooltips for common controls. Edit local skin source to customize them. |
| `captions` | Add `<track kind="captions">` or `<track kind="subtitles">`; preset skins show captions controls when tracks are available. |
| `previewThumbnails` | Add `<track kind="metadata" label="thumbnails">`; preset video skins show slider thumbnails when thumbnail cues are available. |
| `quality` | The quality menu appears when the media exposes renditions, such as HLS or DASH. Plain MP4 source arrays do not currently become a quality menu automatically. |
| `speed` | The preset settings menu uses a fixed rate list; `speed.options` does not carry over. See [Known gaps](https://videojs.org/docs/framework/react/guides/migrate-from-plyr#known-gaps). |
| `fullscreen` | Native fullscreen is supported. Video.js has no equivalent of Plyr’s full-window fallback. |
| `provider: 'vimeo'` | Use the Vimeo media component inside the player skin as shown in [Vimeo](https://videojs.org/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://videojs.org/docs/framework/react/guides/migrate-from-plyr#youtube) above. |
| `storage` | Persist preferences in your app; see [Remember user preferences](https://videojs.org/docs/framework/react/guides/user-preferences). |
| `i18n` | English is the default. Select a locale with an i18n provider or provide custom translations. See [Internationalization](https://videojs.org/docs/framework/react/guides/migrate-from-plyr#internationalization). |
| `ads` | Unsupported at this time. |

When enabling captions without a previous selection in this player instance, `toggleSubtitles()` prefers a track matching `navigator.language`, then falls back to the first available caption or subtitle track. For an authored track that should show on load, add `default`. See [Show captions and subtitles](https://videojs.org/docs/framework/react/guides/captions).

## 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://videojs.org/docs/framework/react/guides/migrate-from-plyr#edit-skin-source) and edit it. A component you add as a child of a packaged skin does not appear in its control bar.

If your app already has a custom control bar, build it from individual [UI components](https://videojs.org/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 a ready-made skin’s source to your project when you need to change its controls or layout.

## Use the imperative API

Use [store actions](https://videojs.org/docs/framework/react/reference/api/player-store) for playback, seeking, volume, fullscreen, and captions:

| Plyr | Video.js v10 |
| --- | --- |
| `player.play()`, `player.pause()` | `play()`, `pause()` |
| `player.currentTime = 10` | `seek(10)` |
| `player.volume = 0.5` | `setVolume(0.5)`, which also unmutes |
| `player.muted = true` | `setMuted(true)` |
| `player.speed = 1.5` | `setPlaybackRate(1.5)` |
| `player.fullscreen.enter()`, `player.fullscreen.exit()` | `requestFullscreen()`, `exitFullscreen()` |
| `player.fullscreen.toggle()` | `isFullscreen ? exitFullscreen() : requestFullscreen()` |
| `player.toggleCaptions()` | `toggleSubtitles()` |

Plyr’s [volume setter](https://github.com/sampotts/plyr/blob/v3.8.4/src/js/plyr.js#L507-L542) unmutes for values above zero, as `setVolume` does. Set `media.volume` directly only when you intend to preserve mute state.

If the volume is `0`, `setMuted(false)` also sets it to `0.25`. To unmute and keep a zero volume, set `media.muted` directly.

Native media methods and properties also update player state through media events. To change content, set `src` on the media component. If the new source needs a different playback engine, replace the component, such as moving from `Video` to `HlsJsVideo`. The player UI follows the attached media.

Import the preset’s [`usePlayer`](https://videojs.org/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/neutral-skin.css';
import { NeutralVideoSkin, usePlayer, Video, VideoPlayer } from '@videojs/react/video';

function CurrentTime() {
  const currentTime = usePlayer((state) => state.currentTime);
  return <output>{Math.round(currentTime)} seconds</output>;
}

export function AppVideoPlayer() {
  return (
    <VideoPlayer>
      <NeutralVideoSkin>
        <Video src="/video.mp4" playsInline />
        <CurrentTime />
      </NeutralVideoSkin>
    </VideoPlayer>
  );
}
```

The same hook selects actions: `usePlayer((state) => state.play)` returns a function you can call from your own UI.

For video-backed media, a `ref` points to the rendered `HTMLVideoElement`. YouTube and Vimeo refs point to an `HTMLIFrameElement`. To call media methods on those embeds, pass a `mediaRef`, which receives the playback adapter, or call `useMedia()` from a component inside the player.

`useMedia()` returns the Video.js media object. If that object exposes an `engine` property, use it to access the playback engine.

## Rewrite styles

Like Plyr, Video.js skins let you customize colors with CSS custom properties. [Add the skin source to your project](https://videojs.org/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 for content on the accent color. To choose that text color yourself, set `--media-accent-text-color`. `--media-border-radius` and `--media-scale-unit` cover rounding and control sizing. See [Customize skins](https://videojs.org/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 TypeScript components and styles become local files that need a build step. A CDN-only page must add a build step before it can use this source. [Customize skins](https://videojs.org/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). For application-managed persistence, follow [Remember user preferences](https://videojs.org/docs/framework/react/guides/user-preferences).
- Playback rates are fixed at `0.2`, `0.5`, `0.7`, `1`, `1.2`, `1.5`, `1.7`, and `2`. Plyr’s `speed.options` has no equivalent yet ([#1404](https://github.com/videojs/v10/issues/1404)).
- Plyr’s full-window fullscreen fallback has no matching Video.js feature. Test fullscreen on your supported browsers; see [Browser support](https://videojs.org/docs/framework/react/guides/browser-support).
- Plain MP4 source arrays with `size` metadata do not automatically create a quality menu. Use Mux, HLS, or DASH for adaptive quality when possible.
- Preset skins segment the time slider and show chapter titles when the media includes a default `<track kind="chapters">`. Cue points are not implemented 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)). To disable auto-hide, set `visibility="always"` on the controls component in a custom layout or installed skin source. Packaged skins do not expose this setting.
- Native controls are not automatically removed when custom controls load; see [#1160](https://github.com/videojs/v10/issues/1160).

## Related pages

### Guides

- [Features](https://videojs.org/docs/framework/react/guides/features): The state and actions each feature adds to the player
- [Media sources](https://videojs.org/docs/framework/react/guides/media-sources): Set what a media component plays and how its engine plays it with the structured source property
- [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins): Style a packaged Video.js skin or add its source to change controls, layout, styles, and interactions

---

<!-- Source: https://videojs.org/docs/framework/react/guides/migrate-from-media-chrome -->

# Migrate from Media Chrome

Move a Media Chrome player to Video.js v10, mapping its controller, controls, styles, and imperative calls

Replace Media Chrome’s controller with a Video.js player and container, then migrate your controls to React components. Keep the playback sources and interactions your app needs. Rebuild each control’s visible contents and styles.

> **Note**
>
> This guide is for apps that build their own player from Media Chrome elements. If you use Mux Player, follow [Migrate from Mux Player](https://videojs.org/docs/framework/react/guides/migrate-from-mux-player) instead.

## AI Quickstart

Paste this prompt into your coding agent:

```
Migrate this project's Media Chrome player to Video.js v10 for React. Use @videojs/react.

Run `npx @videojs/cli agents skills` to get the Video.js skill installation instructions. Follow the printed steps for your agent. If they require a session reload, reload the session and continue with this prompt. If you can't run commands, use the installation instructions at https://github.com/videojs/skills. Use the skill throughout this migration.

Read the migration guide at https://videojs.org/docs/framework/react/guides/migrate-from-media-chrome, including its Known gaps section. Inspect the existing player and list its media URLs, source formats, tracks, options, custom controls, event handlers, and integrations. Compare that list with the known gaps and report unsupported requirements before changing code. Keep the existing media URLs and required behavior throughout the migration.

For installation guidance, read https://videojs.org/docs/framework/react/llms.txt and follow its link to the installation guide. Keep using that online index for a CDN installation.

From the application root, run `npx @videojs/cli agents init` without flags to list installation options and their accepted values.

Choose values for these options:
- --media and --source-url: the existing content and playback requirements.
- --method: the installation method.
- --preset, --skin, and --extensions: the player UI and integrations.

Add those options to `npx @videojs/cli agents init --framework react --project existing` and run the command to print the installation plan. Follow any version-mismatch notice. Both CLI commands print instructions without changing project files. Use the printed plan to install Video.js and configure the player.

After installing a package, switch to node_modules/@videojs/react/docs/llms.txt for documentation matching its version.

Implement the migration. Then verify playback, captions, controls, and any analytics integration on every browser the project supports.
```

## Before you begin

Check [Known gaps](https://videojs.org/docs/framework/react/guides/migrate-from-media-chrome#known-gaps) for controller options and preferences your app relies on. List your media sources, custom controls, event handlers, and theme rules.

Install Video.js and choose a [preset](https://videojs.org/docs/framework/react/guides/presets) (see [Installation](https://videojs.org/docs/guides/installation/react)). If the preset’s ready-made skin has the controls you need, start with it. To keep a custom control bar, build it from the individual Video.js UI components instead.

```bash
npm install @videojs/react
```

## Map the controller

The examples use the same MP4 source before and after migration. For HLS, DASH, or an embed, keep your existing source and choose its [media component](https://videojs.org/docs/framework/react/guides/media-sources).

Media Chrome wraps a slotted `<video slot="media">` in a single `<media-controller>`. Video.js splits that into two components. The player owns state and renders nothing. The container holds the media and controls. Put the media directly inside the container.

```html
<!-- Media Chrome -->
<media-controller>
  <video slot="media" src="video.mp4"></video>
  <media-control-bar>
    <media-play-button></media-play-button>
  </media-control-bar>
</media-controller>
```

Media Chrome’s React package wraps its custom elements. `@videojs/react` ships native components instead. `VideoPlayer` comes from the video [preset](https://videojs.org/docs/framework/react/guides/presets), and `Container` holds the media and controls:

```tsx
'use client';

import { Container, Controls, PlayButton } from '@videojs/react';
import { Video, VideoPlayer } from '@videojs/react/video';
import './player.css';

export function MyPlayer() {
  return (
    <VideoPlayer>
      <Container className="app-player-container">
        <Video className="app-player-media" src="video.mp4" playsInline />
        <Controls.Root>
          <Controls.Content className="app-player-controls">
            <PlayButton
              render={(props, state) => (
                <button {...props} className="player-play-button">
                  {state.paused ? 'Play' : 'Pause'}
                </button>
              )}
            />
          </Controls.Content>
        </Controls.Root>
      </Container>
    </VideoPlayer>
  );
}
```

Create `player.css` with the rules below for layout, button styling, and control visibility. If your framework does not allow global CSS imports in components, import `player.css` from the entry point your app uses for global styles. Alternatively, add these rules to your app’s global stylesheet and remove the `./player.css` import:

**player.css**

```css
.app-player-container {
  position: relative;
  width: 100%;
  aspect-ratio: 16 / 9;
}

.app-player-media {
  display: block;
  width: 100%;
  height: 100%;
  object-fit: contain;
}

.app-player-controls {
  position: absolute;
  inset-inline: 0;
  bottom: 0;
  display: flex;
  padding: 0.75rem;
  background: rgb(0 0 0 / 70%);
}

.app-player-controls:not([data-visible]) {
  visibility: hidden;
  pointer-events: none;
}

.player-play-button {
  padding: 0.5rem;
  color: white;
  cursor: pointer;
  background: #222;
  border: 1px solid white;
  border-radius: 0.25rem;
}

.player-play-button:focus-visible {
  outline: 2px solid white;
  outline-offset: 2px;
}
```

A preset player has a fixed set of [features](https://videojs.org/docs/framework/react/guides/features). For a custom set, call [`createPlayer`](https://videojs.org/docs/framework/react/reference/api/create-player) once outside your React component. Pass it the feature list, then use the `Player` component and typed `usePlayer` hook it returns.

```tsx
import { createPlayer } from '@videojs/react';
import { videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });
```

Read player state with [`usePlayer`](https://videojs.org/docs/framework/react/reference/api/use-player), `useMedia`, and [`useStore`](https://videojs.org/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 called in the component that renders `VideoPlayer` or `Player` is outside that provider. Call the hook from a child component.

## Map controller attributes

Media Chrome configures behavior through `<media-controller>` attributes. Video.js v10 has no single controller component, so these settings move to three places:

- **Player features** — playback behavior that comes from the player’s feature set. A preset includes a fixed feature set. With `createPlayer`, you choose the feature set.
- **`Container` and `Controls`** — layout, focus, and autohide.
- **Dedicated components** — `Hotkey`, `Gesture`, and similar components, 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 hide after inactivity by default. For `autohide="-1"`, set `visibility="always"` on `Controls.Root`. The delay is not configurable yet; see [Known gaps](https://videojs.org/docs/framework/react/guides/migrate-from-media-chrome#known-gaps). |
| `fullscreenelement` | `Container` | Fullscreen targets the container element. |
| `gesturesdisabled` | `disabled` on each `Gesture`, or omit it | Media Chrome disables all gestures at once. In Video.js, set `disabled` on each `Gesture` or omit it. |
| `nohotkeys` | `disabled` on each `Hotkey`, or omit it | Media Chrome disables all hotkeys at once. In Video.js, set `disabled` on each `Hotkey` or omit it. |
| `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` | `<track default>` for authored tracks | Add `default` to an authored captions or subtitles track. For tracks supplied by a provider or manifest, Video.js has no player-level setting that picks the default. |
| `defaultstreamtype` | `streamType` feature | Partial support. Video.js reads the stream type from the media. You cannot set a default stream type for use before the media loads. |
| `liveedgeoffset`, `seektoliveoffset` | live media engine | Live-edge behavior lives in the playback engine, not a UI attribute. |
| `lang` | `I18nProvider` | Wrap the player in `I18nProvider` and pass `locale`. See [Internationalize the player](https://videojs.org/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';

<>
  <Hotkey keys="Space" action="togglePaused" />
  <Hotkey keys="m" action="toggleMuted" />
  <Hotkey keys="ArrowRight" action="seekStep" value={5} />
  <Hotkey keys="ArrowLeft" action="seekStep" value={-5} />
</>
```

In a custom layout, render these components inside the player’s `Container`. With installed skin source, edit its existing hotkey declarations.

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

Declare each tap or double-tap behavior with a `Gesture` component. For example, declare a tap that toggles playback, or a double-tap that seeks or enters fullscreen:

```tsx
import { Gesture } from '@videojs/react';

<>
  <Gesture type="tap" action="togglePaused" pointer="mouse" region="center" />
  <Gesture type="doubletap" action="seekStep" value={-10} region="left" />
  <Gesture type="doubletap" action="seekStep" value={10} region="right" />
</>
```

In a custom layout, render these components inside the player’s `Container`. With installed skin source, edit its existing gesture declarations. A packaged skin already declares its own gestures, so do not add duplicates.

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. Start with these name changes:

| 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 `type` to choose the value |
| `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://videojs.org/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://videojs.org/docs/framework/react/guides/ui-components) concept for the full set.

`Poster` also works differently. Put the poster URL on `VideoPlayer`; `Poster.Root` owns its state and `Poster.Image` accepts image attributes such as `alt`. If you set `srcSet` on `Poster.Image`, it overrides the player poster URL. Pair `srcSet` with `sizes` for responsive images.

Inside your custom player’s container, render the poster beside its media and controls:

```tsx
import { Poster } from '@videojs/react';

<Poster.Root>
  <Poster.Image alt="" />
</Poster.Root>
```

## Rewrite your styles

Media Chrome reflects state in attributes such as `mediapaused`. Video.js uses `data-*` attributes such as `data-paused`.

```css
/* Media Chrome */
media-play-button[mediapaused] .play-icon { display: inline; }
```

```css
/* Video.js React: target the className on your rendered button */
.player-play-button[data-paused] { /* your paused-button styles */ }
```

Values that change continuously, such as slider position, 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 the shared prefix does not make their variables compatible. 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 colors fewer parts of the skin. |
| `--media-secondary-color` | no direct equivalent | Add the skin source and write CSS for this color. |
| `--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 eight custom properties:

- Colors: `--media-accent-color`, `--media-accent-text-color`, and `--media-border-color`.
- Corners: `--media-border-radius`.
- Interface font: `--media-font-family`.
- Media and poster fit and position: `--media-object-fit` and `--media-object-position`.
- Control sizing: `--media-scale-unit`.

See [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin) for their meanings and defaults. Do not assume another Media Chrome variable will work because its name starts with `--media-`.

## Themes become skins

Media Chrome’s `<template>`-based themes (`media-theme`) become Video.js [skins](https://videojs.org/docs/framework/react/guides/skins) and [presets](https://videojs.org/docs/framework/react/guides/presets). Start from a preset, then [add its skin source to your project](https://videojs.org/docs/framework/react/guides/customize-skins#style-skin-source).

React skins do not use Shadow DOM. Use `render` props when you build individual controls. Add a ready-made skin’s source to your project when you need to change its controls or layout.

## Control the player imperatively

Use [store actions](https://videojs.org/docs/framework/react/reference/api/player-store) such as `play`, `pause`, `seek`, `setVolume`, `requestFullscreen`, and `exitFullscreen` to control playback and UI state.

Select an action with the same [`usePlayer`](https://videojs.org/docs/framework/react/reference/api/use-player) hook you read state with:

```tsx
import { usePlayer } from '@videojs/react/video';

function FullscreenShortcut() {
  const isFullscreen = usePlayer((state) => state.isFullscreen);
  const requestFullscreen = usePlayer((state) => state.requestFullscreen);
  const exitFullscreen = usePlayer((state) => state.exitFullscreen);

  return (
    <button type="button" onClick={() => isFullscreen ? exitFullscreen() : requestFullscreen()}>
      Toggle fullscreen
    </button>
  );
}
```

Keep native media calls such as `video.play()` and assignments such as `video.currentTime = 30`. Video.js updates player state from media events. Set `src` on the media component to change content, and replace the component when the source needs a different playback engine.

For video-backed media, a `ref` points to the rendered `HTMLVideoElement`. YouTube and Vimeo refs point to an `HTMLIFrameElement`. To call media methods on those embeds, pass a `mediaRef`, which receives the playback adapter, or call `useMedia()` from a component inside the player.

`useMedia()` returns the Video.js media object. If that object exposes an `engine` property, use it to access the playback engine.

## Known gaps

These Media Chrome features have no direct equivalent yet. Several can be approximated; see [Workarounds](https://videojs.org/docs/framework/react/guides/migrate-from-media-chrome#workarounds).

- No configurable `autohide` delay and no `autohideovercontrols` ([#1728](https://github.com/videojs/v10/issues/1728)). To disable autohide (`autohide="-1"`), set `visibility="always"` on the controls component; see [Workarounds](https://videojs.org/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 for jumping between chapters ([#1873](https://github.com/videojs/v10/issues/1873))
- Cue points are not supported ([#1442](https://github.com/videojs/v10/issues/1442))

Chapters still work. Add a `<track kind="chapters">` with the `default` attribute. The packaged skins then split the time slider into chapter segments and show the chapter title on hover, via `TimeSlider.Chapters` and `TimeSlider.ChapterTitle`.

## Workarounds

### Disable autohide (`autohide="-1"`)

Set `visibility="always"` on `Controls.Root` to keep the controls visible regardless of activity. Packaged skins do not expose this prop. To keep a packaged skin’s look, [add its source to your project](https://videojs.org/docs/framework/react/guides/customize-skins#style-skin-source) and set `visibility="always"` on its controls component.

### Breakpoints

For custom UI, add a class to your container and another to the controls you want to change. Define and query your own CSS container:

```css
.app-player-container {
  container-type: inline-size;
  container-name: app-player;
}

@container app-player (width > 40rem) {
  .app-player-controls { /* your wide layout */ }
}
```

Packaged HTML skin controls are inside Shadow DOM; external selectors cannot reach them. React skin selectors are private. To change a packaged skin’s responsive layout, [add its source to your project](https://videojs.org/docs/framework/react/guides/customize-skins#style-skin-source) and edit the container queries in its local styles.

### Default duration

There is no player input for a duration placeholder. Set `preload="metadata"` to request the duration before playback. The duration is available only after the network request and engine loading finish. If you defer loading, render a static placeholder in your own UI.

### Preference persistence

Media Chrome remembers volume, muted state, and language across sessions. Video.js does not persist these preferences. Follow [Remember user preferences](https://videojs.org/docs/framework/react/guides/user-preferences) to restore and save them in your app.

Actions throw before the media attaches. Wait until `store.target` is set, restore the saved values, and then start saving changes. For captions or quality, also wait for the relevant track or rendition list before restoring a selection.

### 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. As a workaround, build a custom live control that reads player state through `selectLive` and `selectTime`.

## See also

- [Installation](https://videojs.org/docs/guides/installation/react)
- [UI components](https://videojs.org/docs/framework/react/guides/ui-components)
- [Skins](https://videojs.org/docs/framework/react/guides/skins) and [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins)

---

<!-- Source: https://videojs.org/docs/framework/react/guides/migrate-from-vidstack -->

# Migrate from Vidstack

Move a Vidstack Player integration to Video.js 10, mapping the player, providers, layouts, and media store onto composed components

Vidstack Player gives you one `<media-player>` that holds state, picks a provider from `src`, and hosts a layout you configure with props, slots, and CSS variables.

Video.js 10 grew out of the same ideas: composed, accessible components, one store per player, and state you can style against. The teams behind Vidstack, Plyr, Media Chrome, and Video.js now focus their work on Video.js. The code is new, though, and the jobs `<media-player>` did are split across smaller pieces. Most of this guide is about where each Vidstack concept moved.

> **Note**
>
> We’ll merge priority security patches into Vidstack Player 1.x until January 2028. After that, Vidstack won’t receive further updates. This guide covers Vidstack 1.x.

> **Caution**
>
> Plan this as a rewrite of your player setup, not a find-and-replace. Many names survive, such as `media-play-button`, `data-paused`, and `--media-font-family`, but a matching name doesn’t mean a matching API.

## AI Quickstart

The [Video.js skill](https://github.com/videojs/skills) teaches coding agents how Video.js 10 is composed and points them at documentation that matches your installed version. This prompt installs it and starts the migration.

Paste this prompt into your coding agent:

```
Migrate this project's Vidstack player to Video.js v10 for React. Use @videojs/react.

Run `npx @videojs/cli agents skills` to get the Video.js skill installation instructions. Follow the printed steps for your agent. If they require a session reload, reload the session and continue with this prompt. If you can't run commands, use the installation instructions at https://github.com/videojs/skills. Use the skill throughout this migration.

Read the migration guide at https://videojs.org/docs/framework/react/guides/migrate-from-vidstack, including its Known gaps section. Inspect the existing player and list its media URLs, source formats, tracks, options, custom controls, event handlers, and integrations. Compare that list with the known gaps and report unsupported requirements before changing code. Keep the existing media URLs and required behavior throughout the migration.

For installation guidance, read https://videojs.org/docs/framework/react/llms.txt and follow its link to the installation guide. Keep using that online index for a CDN installation.

From the application root, run `npx @videojs/cli agents init` without flags to list installation options and their accepted values.

Choose values for these options:
- --media and --source-url: the existing content and playback requirements.
- --method: the installation method.
- --preset, --skin, and --extensions: the player UI and integrations.

Add those options to `npx @videojs/cli agents init --framework react --project existing` and run the command to print the installation plan. Follow any version-mismatch notice. Both CLI commands print instructions without changing project files. Use the printed plan to install Video.js and configure the player.

After installing a package, switch to node_modules/@videojs/react/docs/llms.txt for documentation matching its version.

Implement the migration. Then verify playback, captions, controls, and any analytics integration on every browser the project supports.
```

Once Video.js is installed, the agent switches to the docs that ship with the package, which match your version, so it doesn’t rely on training data that mostly describes older players. See [Build with AI](https://videojs.org/docs/framework/react/guides/build-with-ai) to install the skill yourself or give your tool the docs another way.

## Before you migrate

Two checks save the most time.

**Compare your features with [Known gaps](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#known-gaps).** Saved preferences, the chapters menu, caption style settings, audio gain, clipping, and non-VTT captions have no Video.js equivalent yet. If your player depends on one of them, that shapes your timeline more than anything else in this guide.

**Migrate one player at a time if you need to.** Neither `@vidstack/react` nor `@videojs/react` registers custom elements, so both can render in the same app while you move players across. Remove `@vidstack/react` and its stylesheets once nothing imports them. While Vidstack’s player styles are loaded, they also give every `<video>` without a `width` or `height` a 16:9 box, Video.js media included.

## Three pieces instead of one

In Vidstack, `<media-player>` does most of the work. It holds state, selects and loads a provider, acts as the box you size and take fullscreen, carries the state attributes you style against, and listens for keyboard shortcuts.

Video.js 10 splits those jobs:

**The player** holds state and hands it to everything inside it. It draws nothing and takes no layout. Which state it holds depends on the [features](https://videojs.org/docs/framework/react/guides/features) it’s built from.

**The media** plays the video. This is where Vidstack’s *provider* went, except you choose it yourself: a plain `<video>` for progressive files, or a [media component](https://videojs.org/docs/framework/react/guides/media-sources) for HLS, DASH, YouTube, Vimeo, and Mux. There’s no `<media-provider>`; the media component sits inside the skin.

**The skin** is the UI, and it’s where Vidstack’s *layout* went. Every skin renders a container, the box that sizes the player, goes fullscreen, and receives gestures and hotkeys.

```tsx
<VideoPlayer>
  <VideoSkin>
    <Video src="/video.mp4" playsInline />
  </VideoSkin>
</VideoPlayer>
```

Note the nesting. A Vidstack layout sits *next to* `<media-provider>`; a Video.js skin *wraps* the media.

### Terminology

| Vidstack | Video.js 10 |
| --- | --- |
| Player | Player, which only holds state, plus the skin’s container |
| Provider | Media, and its playback **engine** |
| Layout (Default, Plyr) | Skin (Default, Neutral) |
| Video or audio layout, matched by view type | The video or audio **preset**, chosen when you import it |
| Default Theme | Skin source you add to your project |
| Slots | Editing skin source |
| Media store, media state | Player store, player state, composed from **features** |
| Request, remote control | Action |
| `can*` flags | Availability: `available`, `unavailable`, or `unsupported` |
| Stream type `live:dvr` | A live preset. DVR streams report `targetLiveWindow` as `Infinity` |
| Keyboard shortcuts | Hotkeys, one per shortcut |
| Keyboard display | Status indicators |
| Announcer | Status announcer |
| Speed | Playback rate |
| Quality | Video rendition in state; still “quality” in the UI |
| Google Cast | Cast, through the Google Cast extension |
| Plugins (bundler plugins) | None; imports are explicit. Behavior add-ons are **extensions** |

“Remote” also changes meaning. Vidstack’s remote control dispatched requests; in Video.js, remote playback means AirPlay and Cast.

## Your first player

Here’s a typical Vidstack player with the Default Layout, captions, thumbnails, and a poster:

```tsx
import '@vidstack/react/player/styles/default/theme.css';
import '@vidstack/react/player/styles/default/layouts/video.css';
import { MediaPlayer, MediaProvider, Poster, Track } from '@vidstack/react';
import { defaultLayoutIcons, DefaultVideoLayout } from '@vidstack/react/player/layouts/default';

export function Player() {
  return (
    <MediaPlayer title="Sprite Fight" src="/video.mp4" poster="/poster.jpg" playsInline>
      <MediaProvider>
        <Poster className="vds-poster" />
        <Track kind="captions" src="/captions/en.vtt" lang="en" label="English" default />
      </MediaProvider>
      <DefaultVideoLayout thumbnails="/storyboard.vtt" icons={defaultLayoutIcons} />
    </MediaPlayer>
  );
}
```

Install `@videojs/react`:

```bash
npm install @videojs/react
```

The video [preset](https://videojs.org/docs/framework/react/guides/presets) gives you a player, a skin, and a media component that already fit together:

```tsx
'use client';

import '@videojs/react/video/skin.css';
import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';

export function Player() {
  return (
    <VideoPlayer title="Sprite Fight" poster="/poster.jpg">
      <VideoSkin style={{ aspectRatio: '16 / 9' }}>
        <Video src="/video.mp4" playsInline>
          <track kind="captions" src="/captions/en.vtt" srcLang="en" label="English" default />
          <track kind="metadata" src="/storyboard.vtt" label="thumbnails" default />
        </Video>
      </VideoSkin>
    </VideoPlayer>
  );
}
```

What changed:

- **No `MediaProvider`.** `Video` is the media, and it sits inside the skin.
- **`src` and `playsInline` moved to the media.** `title` and `poster` stay on the player, and the skin renders them.
- **`Track` became a native `<track>`.** Use `srcLang` instead of `lang`.
- **Thumbnails are a track.** The `thumbnails` layout prop becomes a `<track kind="metadata" label="thumbnails" default>` on the media.
- **No `icons` prop and no theme stylesheet.** The skin ships its icons, and one stylesheet covers the whole skin.
- **Set the aspect ratio yourself.** Vidstack’s base styles gave video a 16:9 box by default. Video.js skins don’t, so size the skin with CSS.

The preset entry already marks itself as client code, so this file doesn’t need `'use client'` yet. Keep it in Next.js and other React Server Components setups once the file uses hooks such as `usePlayer`, or passes functions such as `renderPoster`. `VideoPlayer` takes only its config props and children. It renders no element, so it takes no `className`, `style`, or `ref`; style the skin instead.

If you used the Plyr Layout, start from the Neutral skin instead. It’s the closer match to a classic control bar, and [Migrate from Plyr](https://videojs.org/docs/framework/react/guides/migrate-from-plyr) maps the Plyr options that layout mirrored.

## Where your player props went

`<media-player>` accepted about fifty props. In Video.js they scatter in four directions:

1. **Media attributes** move to the media component, where the browser already understands them.
2. **Player metadata**, the title and poster, stays on the player so the skin can render it.
3. **Playback values** such as volume and current time become actions you call.
4. **Behavior** such as live UI, shortcuts, and casting becomes a choice of preset, component, or extension.

| Vidstack `MediaPlayer` | Video.js 10 |
| --- | --- |
| `src` | `src` or `source` on the media. See [Providers become media components](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#providers-become-media-components) |
| `autoPlay`, `muted`, `loop`, `controls`, `playsInline`, `preload`, `crossOrigin` | The same props on the media. Where Vidstack took `crossOrigin` as `true`, pass `""` or `"anonymous"` |
| `title`, `poster` | `title` and `poster` on `VideoPlayer` |
| `aspectRatio` | CSS `aspect-ratio` on the skin |
| `volume`, `currentTime`, `playbackRate`, `paused` | The `setVolume`, `seek`, `setPlaybackRate`, `play`, and `pause` actions. See [Drive playback](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#drive-playback) |
| `viewType` | The audio or video preset |
| `streamType` | A live preset. See [Live streams](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#live-streams) |
| `preferNativeHLS` | `source.preferPlayback: 'native'` on `HlsJsVideo`, or `NativeHlsVideo` |
| `fullscreenOrientation` | `orientationLockFeature` and `orientationLockType`. See [Fullscreen and orientation](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#fullscreen-and-orientation) |
| `keyShortcuts`, `keyTarget`, `keyDisabled` | Hotkeys. See [Keyboard shortcuts and gestures](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#keyboard-shortcuts-and-gestures) |
| `googleCast` | `receiver` on the Google Cast extension. See [AirPlay and Google Cast](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#airplay-and-google-cast) |
| `controlsDelay`, `hideControlsOnMouseLeave` | Not configurable. Controls hide after 2 seconds and when the pointer leaves ([#1728](https://github.com/videojs/v10/issues/1728)) |
| `load`, `posterLoad` | No equivalent ([#3043](https://github.com/videojs/v10/issues/3043)). See [Loading](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#loading) |
| `storage` | No equivalent ([#944](https://github.com/videojs/v10/issues/944)). See [Remember user preferences](https://videojs.org/docs/framework/react/guides/user-preferences) |
| `duration` | No equivalent ([#1729](https://github.com/videojs/v10/issues/1729)) |
| `clipStartTime`, `clipEndTime` | No equivalent ([#3040](https://github.com/videojs/v10/issues/3040)) |
| `liveEdgeTolerance`, `minLiveDVRWindow` | No equivalent ([#1730](https://github.com/videojs/v10/issues/1730)) |
| `artist`, `artwork` | No equivalent; Video.js doesn’t set Media Session metadata ([#3042](https://github.com/videojs/v10/issues/3042)) |
| `logLevel` | No equivalent ([#1406](https://github.com/videojs/v10/issues/1406)); development builds print warnings |

Vidstack queued `paused`, `volume`, and the other playback props until the media could play. Video.js doesn’t queue: most actions fail until the player has attached to its media, `seek()` included, which only waits for metadata once attached. Call them from event handlers.

Don’t call them from a mount effect inside the player. React runs a child’s effects before the player’s, so the player hasn’t attached yet.

## Providers become media components

Vidstack’s `<media-provider>` read `src`, guessed a type from the extension or a `HEAD` request, and loaded the matching provider. Video.js doesn’t guess. You pick the media component for your source, and that choice is the playback engine choice. Swapping one for another is a component change, and the rest of the player keeps working.

| Vidstack source | Video.js 10 media | Package |
| --- | --- | --- |
| MP4, WebM, and other files | `Video` from `@videojs/react/video`, or `Audio` in the audio preset | included |
| HLS | [`HlsJsVideo`](https://videojs.org/docs/framework/react/reference/components/hlsjs-video), the closest match to Vidstack’s hls.js provider | `@videojs/hlsjs-video` |
| HLS, smaller bundle | [`HlsVideo`](https://videojs.org/docs/framework/react/reference/components/hls-video), built on Video.js’s own engine | included |
| HLS, browser only | [`NativeHlsVideo`](https://videojs.org/docs/framework/react/reference/components/native-hls-video) | included |
| DASH | [`DashVideo`](https://videojs.org/docs/framework/react/reference/components/dash-video), or [`ShakaVideo`](https://videojs.org/docs/framework/react/reference/components/shaka-video) for live DASH | `@videojs/dash-video`, `@videojs/shaka-video` |
| YouTube | [`YouTubeVideo`](https://videojs.org/docs/framework/react/reference/components/youtube-video) | `@videojs/youtube-video` |
| Vimeo | [`VimeoVideo`](https://videojs.org/docs/framework/react/reference/components/vimeo-video) | `@videojs/vimeo-video` |
| Remotion | No equivalent ([#3053](https://github.com/videojs/v10/issues/3053)) | |

Import each media component from `@videojs/react/media/<name>`, for example `@videojs/react/media/hlsjs-video`.

### HLS and DASH

Vidstack loaded hls.js and dash.js from jsDelivr at runtime unless you passed a `library`. Video.js media packages bundle their engine, so there’s no `library` option, no `hls-lib-*` or `dash-lib-*` events, and no CDN host to allow in your Content Security Policy. dash.js also moves from version 4 to version 5; check your dash.js settings against its migration notes.

Engine configuration moves from the `provider-change` event to the media’s `source`:

```tsx
// Vidstack
import { isHLSProvider, MediaPlayer, type MediaProviderAdapter } from '@vidstack/react';

function onProviderChange(provider: MediaProviderAdapter | null) {
  if (isHLSProvider(provider)) provider.config = { maxBufferLength: 60 };
}

<MediaPlayer src="/stream.m3u8" onProviderChange={onProviderChange}>
  {/* … */}
</MediaPlayer>
```

```bash
npm install @videojs/hlsjs-video
```

```tsx
// Video.js 10
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';

<VideoPlayer>
  <VideoSkin>
    <HlsJsVideo source={{ src: '/stream.m3u8', engine: { hlsJs: { maxBufferLength: 60 } } }} playsInline />
  </VideoSkin>
</VideoPlayer>
```

`source` is replaced, not merged. Changing hls.js options rebuilds the engine; dash.js and Shaka apply new settings to the running one. See [Media sources](https://videojs.org/docs/framework/react/guides/media-sources) for the options every engine shares, such as `preferPlayback`, rendition caps, and DRM.

Where you used `provider.instance` or `onInstance`, read the engine from the media object that `useMedia` returns. `useMedia` doesn’t know which media component you rendered, so check the media with `instanceof HlsJsAdapter` first; that types `engine` as the hls.js instance. `HlsJsAdapter` and `Hls` come from `@videojs/hlsjs-video`, the package you installed for `HlsJsVideo`, which exports them for this kind of low-level access. Outside the player, pass `mediaRef` to `HlsJsVideo` instead: it receives the same `HlsJsAdapter`, so `mediaRef.current?.engine` is already typed as the hls.js instance. Vidstack re-dispatched hls.js events as `onHls*` callbacks; Video.js doesn’t forward engine events, so subscribe on the engine itself:

```tsx
import { useMedia } from '@videojs/react';
import { Hls, HlsJsAdapter } from '@videojs/hlsjs-video';
import { useEffect } from 'react';

function LevelLogger() {
  const media = useMedia();
  const engine = media instanceof HlsJsAdapter ? media.engine : null;

  useEffect(() => {
    if (!engine) return;

    const onLevelSwitched = (_event: unknown, data: { level: number }) => console.log('level', data.level);
    engine.on(Hls.Events.LEVEL_SWITCHED, onLevelSwitched);
    return () => engine.off(Hls.Events.LEVEL_SWITCHED, onLevelSwitched);
  }, [engine]);

  return null;
}
```

`engine` is `null` while the browser’s own HLS is playing. The media builds a new engine when its engine options, DRM, `preferPlayback`, or content type change; a new URL of the same type keeps the current one.

Treat engine access as an escape hatch. It couples your app to one engine, so prefer player state and media events when they cover what you need.

### YouTube and Vimeo

The embeds take a URL, a bare ID, or one of Vidstack’s shorthands as `src`:

- **`youtube/ID` plays from the privacy-enhanced host,** `youtube-nocookie.com`, as it did in Vidstack.
- **`vimeo/ID?hash=HASH` still plays an unlisted video.** In a full Vimeo URL, give the hash as `?h=HASH` or as the last path segment.

A `ref` on `YouTubeVideo` or `VimeoVideo` is the `<iframe>`, which can’t play or seek. Where you called methods on Vidstack’s YouTube or Vimeo provider, pass `mediaRef` to get the adapter that drives the embed:

```tsx
import type { YouTubeAdapter } from '@videojs/youtube-video';

const mediaRef = useRef<YouTubeAdapter>(null);

<YouTubeVideo mediaRef={mediaRef} src="youtube/aqz-KE-bpKQ" />

// In an event handler
if (mediaRef.current) mediaRef.current.currentTime = 30;
```

Vidstack fetched a poster for embeds automatically. Video.js doesn’t ([#3049](https://github.com/videojs/v10/issues/3049)); set `poster` on the player if you want your own image before playback.

> **Caution: Embed privacy defaults changed**
>
> Vidstack loaded YouTube from `youtube-nocookie.com` and asked Vimeo not to track viewers unless you turned cookies on. Video.js plays a YouTube URL from the standard host unless it’s a `youtube-nocookie.com` URL, and sends Vimeo’s `dnt` flag only when you set `source.engine.vimeo.dnt`. Keep the privacy-enhanced behavior by writing YouTube sources as `youtube/VIDEO_ID` shorthands or `youtube-nocookie.com` URLs, and adding `dnt: true` to the Vimeo engine options.

### Choose the media from the URL

We’re working on a media component that picks and loads the right engine from its source, the way `<media-provider>` did. Its API isn’t settled yet; follow [#2160](https://github.com/videojs/v10/issues/2160) for progress.

Until then, [`resolveAdapterType`](https://videojs.org/docs/framework/react/reference/api/resolve-adapter-type) tells you which media component plays a URL, and you render that component with the same `src`. If your app plays sources from a catalog or from user input, a switch on its result covers the common cases:

```tsx
'use client';

import { resolveAdapterType } from '@videojs/react';
import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';
import { lazy, Suspense } from 'react';

const DashVideo = lazy(() => import('@videojs/react/media/dash-video').then((m) => ({ default: m.DashVideo })));
const HlsJsVideo = lazy(() => import('@videojs/react/media/hlsjs-video').then((m) => ({ default: m.HlsJsVideo })));
const VimeoVideo = lazy(() => import('@videojs/react/media/vimeo-video').then((m) => ({ default: m.VimeoVideo })));
const YouTubeVideo = lazy(() => import('@videojs/react/media/youtube-video').then((m) => ({ default: m.YouTubeVideo })));

function Media({ src }: { src: string }) {
  switch (resolveAdapterType(src)) {
    case 'youtube':
      return <YouTubeVideo src={src} />;
    case 'vimeo':
      return <VimeoVideo src={src} />;
    case 'hls':
      return <HlsJsVideo src={src} playsInline />;
    case 'dash':
      return <DashVideo src={src} playsInline />;
    default:
      return <Video src={src} playsInline />;
  }
}

export function Player({ src }: { src: string }) {
  return (
    <VideoPlayer>
      <VideoSkin style={{ aspectRatio: '16 / 9' }}>
        <Suspense>
          <Media key={src} src={src} />
        </Suspense>
      </VideoSkin>
    </VideoPlayer>
  );
}
```

Each embed and streaming component loads with `React.lazy`, so the page only downloads the engine its source needs, the way Vidstack’s provider loaders did. `Video` plays through the browser with no engine, so it’s imported directly. When the media changes, the player detaches from the old one, resets its state, and attaches to the new one; the skin follows.

`resolveAdapterType` recognizes the URLs and shorthands Vidstack’s providers did, plus Wistia, Mux, Cloudflare Stream, Spotify, TikTok, and Twitch, and returns `null` for anything else. Vidstack sent a `HEAD` request when a URL had no file extension; pass the MIME type as the second argument instead. The result names a kind of source, not an engine: `hls` covers every HLS media, so choose one yourself.

For a single source, change the media’s `src` or `source` instead. The same media swaps the URL without being replaced.

### Loading

Vidstack waited until the player was visible before it loaded the provider (`load="visible"`), and embeds loaded lazily with preconnect hints. Video.js media starts loading as soon as it attaches, following its `preload` attribute, and embeds create their iframe right away.

To defer network work, set `preload="none"` on streaming media; hls.js-backed media then waits for playback to fetch segments. For players far down a page, render or import the media when it scrolls into view with your own `IntersectionObserver`. There’s no `startLoading()`; set `src` when you’re ready. Follow [#3043](https://github.com/videojs/v10/issues/3043) for built-in deferred loading and [#1433](https://github.com/videojs/v10/issues/1433) for preconnect hints.

## Layouts become skins

Vidstack rendered the audio and video layouts side by side and matched one at runtime, then switched live controls on by stream type. Video.js gives each case its own [preset](https://videojs.org/docs/framework/react/guides/presets) and skin, chosen when you import it.

| Vidstack | Closest Video.js 10 skin |
| --- | --- |
| `DefaultVideoLayout` | `VideoSkin` from `@videojs/react/video` |
| `DefaultVideoLayout` playing a live stream | `LiveVideoSkin` from `@videojs/react/live-video` |
| `DefaultAudioLayout` | `AudioSkin` from `@videojs/react/audio` |
| `PlyrLayout` | `NeutralVideoSkin` or `NeutralAudioSkin` |
| A custom layout with no controls | `BackgroundVideoSkin` from `@videojs/react/background` |

The video skins cover the Default Layout’s core controls: play, volume, time, the time slider with thumbnails and chapter segments, captions, fullscreen, picture-in-picture, AirPlay, Cast, and a settings menu with quality, audio track, playback rate, and captions. They add an error dialog and on-screen feedback for hotkeys and gestures. The Default Layout’s chapters menu ([#1873](https://github.com/videojs/v10/issues/1873)), accessibility menu, audio boost ([#1135](https://github.com/videojs/v10/issues/1135)), and download button ([#3041](https://github.com/videojs/v10/issues/3041)) have no equivalent yet.

### Map layout props

Packaged skins take almost no props. Most layout props either move somewhere else or need you to [edit the skin source](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#level-3-edit-skin-source).

| `DefaultVideoLayout` prop | Video.js 10 |
| --- | --- |
| `thumbnails` | A `<track kind="metadata" label="thumbnails" default>` on the media |
| `translations` | [i18n](https://videojs.org/docs/framework/react/guides/internationalization); see [Languages](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#languages) |
| `icons` | Built in; edit skin source to swap them |
| `colorScheme` | CSS `color-scheme`; see [Color scheme](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#color-scheme) |
| `smallLayoutWhen` | Container queries built into the skin; see [Responsive layouts](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#responsive-layouts) |
| `slots` | Edit skin source; see [Slots become skin source](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#slots-become-skin-source) |
| `seekStep` | 10 seconds in the skin’s hotkeys and gestures; edit skin source to change it |
| `playbackRates` | A fixed list: `0.2`, `0.5`, `0.7`, `1`, `1.2`, `1.5`, `1.7`, `2` ([#1404](https://github.com/videojs/v10/issues/1404)) |
| `showTooltipDelay` | 600 ms; set `delay` on tooltips in skin source |
| `noGestures`, `noKeyboardAnimations`, `disableTimeSlider`, `menuGroup` | Edit skin source |
| `hideQualityBitrate` | Bitrate shows only to tell apart renditions of the same size |
| `noModal`, `menuContainer` | Not needed. Menus render in the browser’s top layer |
| `audioGains`, `noAudioGain` | No audio gain ([#1135](https://github.com/videojs/v10/issues/1135)) |
| `download` | No equivalent ([#3041](https://github.com/videojs/v10/issues/3041)) |
| `sliderChaptersMinWidth`, `noScrubGesture` | No equivalent |

### Slots become skin source

Vidstack’s `slots` prop inserted, replaced, or removed controls at more than forty named slots, each with `before` and `after` positions. Video.js has no slot API for controls. Children of a packaged skin render with the media, not in the control bar. The two content overrides are `renderPoster` and `renderThumbnail`.

To add, move, or remove a control, add the skin source to your project and edit it. `slots={{ afterCaptionButton: <MyButton /> }}` becomes one line in the copied layout file; `slots={{ pipButton: null }}` becomes a deleted line.

### Customize your player

Vidstack customization climbed from layout props, through CSS variables and slots, to composing your own layout. Video.js has three levels. Try them in order.

#### Level 1: pick a skin

Choose Default, Neutral, or Compat for video, audio, live video, or live audio. See [Skins](https://videojs.org/docs/framework/react/guides/skins).

#### Level 2: restyle it

Packaged skins expose eight public custom properties: `--media-accent-color`, `--media-accent-text-color`, `--media-border-color`, `--media-border-radius`, `--media-font-family`, `--media-object-fit`, `--media-object-position`, and `--media-scale-unit`. That’s far fewer than Vidstack’s layout variables, so expect to reach Level 3 sooner. See [Map theme variables by meaning](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#map-theme-variables-by-meaning) and [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin).

#### Level 3: edit skin source

For changes to controls, layout, or interactions, add the skin source to your project with the [Shadcn registry](https://videojs.org/docs/guides/installation/shadcn?framework=react). The components and styles become local files you own. This is where Vidstack’s slots, icon overrides, and switches such as `noGestures` end up. See [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-skin-source).

To build a layout from scratch, the way you might have composed Vidstack components with the Default Theme, compose the [UI components](https://videojs.org/docs/framework/react/guides/ui-components) inside a container yourself.

## Rewrite your styles

### State attributes

Vidstack reflected about forty state attributes onto the player’s element, so any descendant could style against `[data-media-player][data-paused]`. Video.js puts state on the component it belongs to. `VideoPlayer` renders no element, and `Container` only reflects `data-controls-visible`.

| Vidstack | Video.js 10 |
| --- | --- |
| `[data-paused]`, `[data-ended]`, `[data-started]` on the player | The same attributes on `PlayButton` |
| `[data-waiting]`, `[data-buffering]` | `data-visible` on `BufferingIndicator` |
| `[data-controls]` | `data-controls-visible` on `Container`, `data-visible` on `Controls.Content` |
| `[data-fullscreen]` | `data-fullscreen` on `FullscreenButton`, or `:fullscreen` on the container |
| `[data-pip]` | `data-pip` on `PiPButton` |
| `[data-muted]` | `data-muted` and `data-volume-level` on `MuteButton` |
| `[data-captions]` | `data-active` on `CaptionsButton` |
| `[data-live]`, `[data-live-edge]` | The same attributes on `LiveButton` |
| `[data-seeking]`, `[data-preview]` | `data-seeking`, `data-pointing`, and `data-dragging` on `TimeSlider.Root` |
| `[data-can-fullscreen]`, `[data-can-pip]`, `[data-can-airplay]`, `[data-can-google-cast]` | `data-availability` on the matching button, which renders nothing when unsupported |
| `[data-airplay]`, `[data-google-cast]`, `[data-remote-state]` | `data-airplay-state` and `data-cast-state` on the buttons |
| `[data-error]` | `data-open` on the error dialog |
| `[data-pointer="coarse"]` | `@media (pointer: coarse)` |
| `[data-media-type]`, `[data-view-type]`, `[data-stream-type]` | The preset you chose |
| `[data-focus]`, `[data-hocus]` | `:focus-visible`, `:hover` |

For your own components, you usually don’t need an attribute at all. Read the value with `usePlayer`, or pass a function to `className` on a Video.js component: `className={(state) => …}`.

Some names mean different things now. `data-active` meant a Vidstack slider was being dragged, pointed at, or focused; in Video.js it marks active captions or the chapter that’s playing. `data-orientation` was the screen orientation; now it’s a slider’s axis.

### Map theme variables by meaning

The shared `--media-` prefix is a naming convention, not a compatibility layer. Only `--media-font-family` keeps its name and meaning.

| Vidstack | Video.js 10 |
| --- | --- |
| `--media-brand`, `--video-brand`, `--audio-brand` | `--media-accent-color` |
| `--media-font-family`, `--video-font-family`, `--audio-font-family` | `--media-font-family` |
| `--video-border-radius`, `--audio-border-radius` | `--media-border-radius` |
| `--video-border`, `--audio-border` | `--media-border-color`, color only |
| `--media-button-size`, `--media-time-font-size`, and other size variables | `--media-scale-unit`, which scales spacing, icons, and text together |
| `--media-cue-*`, `--video-captions-offset` | `::cue` styles; the browser renders captions |
| `--media-tooltip-*`, `--media-menu-*`, `--media-slider-*`, `--media-focus-ring*`, `--video-controls-color` | No packaged equivalent; edit skin source |
| `--slider-fill`, `--slider-pointer`, `--slider-progress` | `--media-slider-fill`, `--media-slider-pointer`, `--media-slider-buffer` |
| `--player-width`, `--player-height` | Container queries on `media-root` |

The slider variables are values the component publishes for your styles to read, not inputs you set, the same as in Vidstack. They only gained the `--media-` prefix.

### Tailwind

Vidstack’s Tailwind plugin added state variants like `media-paused:` and `media-can-play:`. Video.js has no plugin; use Tailwind’s built-in `data-*` variants on the component that carries the state. The bare `data-paused:` form needs Tailwind 4; on Tailwind 3, write `data-[paused]:`.

```tsx
// Vidstack
<PlayButton className="media-paused:bg-white" />

// Video.js 10
<PlayButton className="data-paused:bg-white" />
```

Skin source in Tailwind defines its own `media-sm:`, `media-lg:`, and similar variants. Those are container-width breakpoints, not state. The Tailwind skin source needs Tailwind 4.3 or later, and it’s available for React only; HTML skin source uses CSS ([#3055](https://github.com/videojs/v10/issues/3055)). Vidstack’s plugin targeted Tailwind 3.

### Responsive layouts

Vidstack switched to a small layout when `smallWhen` matched the player’s width or height. Video.js skins restyle one layout with container queries against a container named `media-root`, using width only. The breakpoints are fixed in packaged skins; edit them in skin source. For your own layout around the player, write your own `@container` rules.

### Color scheme

Vidstack’s `colorScheme` toggled light and dark classes on the layout. Video.js skins read the inherited CSS `color-scheme`, so `:root { color-scheme: light dark; }` follows the system setting. The audio skins change their palette with the scheme. The video skins stay dark over video; only their border follows it ([#3054](https://github.com/videojs/v10/issues/3054)).

### Icons

`@vidstack/react/icons` becomes `@videojs/react/icons`, with a smaller set of 25 icons in Default, Neutral, and Compat families. Icons take standard SVG props; there’s no `size` prop. Several names changed:

| Vidstack | Video.js 10 |
| --- | --- |
| `ReplayIcon` | `RestartIcon` |
| `MuteIcon` | `VolumeOffIcon` |
| `ClosedCaptionsIcon`, `ClosedCaptionsOnIcon` | `CaptionsOffIcon`, `CaptionsOnIcon` |
| `FullscreenIcon` | `FullscreenEnterIcon` |
| `PictureInPictureIcon`, `PictureInPictureExitIcon` | `PipEnterIcon`, `PipExitIcon` |
| `ChromecastIcon` | `CastEnterIcon`, `CastExitIcon` |
| `AirPlayIcon` | `AirPlayEnterIcon`, `AirPlayExitIcon` |
| `SettingsIcon` | `GearIcon` |
| `SeekForward10Icon`, `SeekBackward10Icon` | `SeekIcon`, mirrored for backward |

Icons such as `download`, `chapters`, and `accessibility` have no Video.js counterpart. Bring your own SVGs for those.

## Map the components

Most Vidstack components have a Video.js counterpart with the same job. What changes is how they compose.

| Vidstack | Video.js 10 |
| --- | --- |
| `MediaPlayer` | `VideoPlayer`, or `Player` from `createPlayer`, plus `Container` |
| `MediaProvider` | The media component: `Video`, `HlsJsVideo`, `YouTubeVideo`, … |
| `PlayButton`, `MuteButton`, `FullscreenButton`, `AirPlayButton`, `LiveButton`, `SeekButton` | Same names |
| `CaptionButton` | `CaptionsButton` |
| `PIPButton` | `PiPButton` |
| `GoogleCastButton` | `CastButton` |
| `ToggleButton` | No equivalent; build one with `useButton` |
| `Tooltip.Root`, `Tooltip.Trigger`, `Tooltip.Content` | `Tooltip.Root`, `Tooltip.Trigger`, `Tooltip.Popup`, plus `Tooltip.Label` and `Tooltip.Shortcut` |
| `Controls.Root`, `Controls.Group` | `Controls.Root`, `Controls.Content`, `Controls.Group` |
| `Gesture` | `Gesture`, with different props; see [Gestures](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#gestures) |
| `MediaAnnouncer` | `StatusAnnouncer`, already in every skin |
| `Poster` | `Poster.Root` and `Poster.Image`, reading the player’s `poster` |
| `Thumbnail.Root`, `Thumbnail.Img` | `Thumbnail.Root`, `Thumbnail.Image` |
| `Time` with `remainder` | `Time.Value` with `type="remaining"` |
| `Title` | `Title` |
| `ChapterTitle` | `TimeSlider.ChapterTitle`, inside the time slider only |
| `Track` | A native `<track>` |
| `Captions`, `Caption.Root` | No equivalent; the browser renders captions |
| `Slider.Root`, `Slider.Track`, `Slider.TrackFill`, `Slider.Thumb` | `Slider.Root`, `Slider.Track`, `Slider.Fill`, `Slider.Thumb` |
| `TimeSlider.Root`, `TimeSlider.Progress`, `TimeSlider.Chapters` | `TimeSlider.Root`, `TimeSlider.Buffer`, `TimeSlider.Chapters` |
| `TimeSlider.Thumbnail.Root`, `TimeSlider.Thumbnail.Img` | `Slider.Thumbnail.Root`, `Slider.Thumbnail.Image` |
| `VolumeSlider.Root` | `VolumeSlider.Root`, or `VolumePopover` for a mute button that opens a slider |
| `Slider.Steps`, `TimeSlider.Video`, `SpeedSlider`, `QualitySlider`, `AudioGainSlider` | No equivalent |
| `Menu.Root`, `Menu.Button`, `Menu.Items` or `Menu.Content` | `Menu.Root`, `Menu.Trigger`, `Menu.Popup`, `Menu.Content` |
| `Menu.Radio`, `RadioGroup.Root` | `Menu.RadioItem`, `Menu.RadioGroup`; radio groups work inside menus only |
| `Menu.Portal` | Not needed; menus render in the top layer |
| `useCaptionOptions`, `useVideoQualityOptions`, `useAudioOptions`, `usePlaybackRateOptions` | `useCaptionsOptions`, `useQualityOptions`, `useAudioTrackOptions`, `usePlaybackRateOptions` |
| `useChapterOptions`, `useAudioGainOptions` | No equivalent |
| Remotion components | No equivalent |

**`asChild` becomes `render`.** Pass an element to merge props into it, the way `asChild` did, or a function that receives props and state:

```tsx
// Vidstack
<Tooltip.Trigger asChild>
  <PlayButton />
</Tooltip.Trigger>

// Video.js 10
<Tooltip.Trigger render={<PlayButton />} />

<PlayButton render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>} />
```

Several roots render no element of their own: `Controls.Root`, `Tooltip.Root`, `Menu.Root`, and `Gesture` among them. Put your classes on `Controls.Content`, `Tooltip.Popup`, and `Menu.Popup`.

A few behaviors changed across the board:

- **Unsupported controls hide themselves.** Vidstack kept them in the DOM without `data-supported`, and you hid them with CSS. Video.js buttons expose `data-availability` and hide when the feature is unsupported.
- **Sliders take focus on the thumb.** Keyboard control moved from the slider root to its thumb, so a slider without a thumb can’t be used from the keyboard.
- **Toggle buttons change their label instead of setting `aria-pressed`.** A play button announces “Play” or “Pause” depending on state.
- **Placement is two props.** `placement="top center"` becomes `side="top"` and `align="center"`, and the rendered placement is reflected as `data-side` and `data-align`.
- **No request events.** Controls call player actions directly, so there’s nothing to intercept with `preventDefault()`.

## Read player state

Vidstack’s media store becomes the player store. Two differences catch most migrations:

- **State keys come from features.** Every Vidstack key always existed. In Video.js, a key exists only when its feature is part of the player, and some live in no preset.
- **Subscriptions don’t track what you read.** Vidstack’s `subscribe` re-ran only when the keys you read changed. The Video.js store notifies on any change; selectors give you change-only updates.

The [player store reference](https://videojs.org/docs/framework/react/reference/api/player-store) lists every state field and action, grouped by the feature that adds it.

| Vidstack | Video.js 10 |
| --- | --- |
| `useMediaState('paused')` | `usePlayer((state) => state.paused)` |
| `useMediaStore()` | `usePlayer((state) => ({ currentTime: state.currentTime, duration: state.duration }))` |
| `useMediaState('paused', playerRef)`, outside the player | Render `VideoPlayer` higher, around the component that reads state |
| `useMediaRemote()` | `usePlayer((state) => state.seek)`, or any other action |
| `useMediaPlayer()` | `usePlayer()` for state and actions, `useContainer()` for the element |
| `useMediaProvider()` | `useMedia()` inside the player, or `mediaRef` on the media component |
| `player.subscribe(callback)` | `usePlayer().subscribe(callback)`, reading values off the store inside |

```tsx
// Vidstack
import { useMediaRemote, useMediaState } from '@vidstack/react';

function SkipIntro() {
  const currentTime = useMediaState('currentTime');
  const remote = useMediaRemote();
  if (currentTime > 30) return null;
  return <button onPointerUp={(event) => remote.seek(30, event.nativeEvent)}>Skip intro</button>;
}
```

```tsx
// Video.js 10
import { usePlayer } from '@videojs/react/video';

function SkipIntro() {
  const currentTime = usePlayer((state) => state.currentTime);
  const seek = usePlayer((state) => state.seek);
  if (currentTime > 30) return null;
  return <button onClick={() => seek(30)}>Skip intro</button>;
}
```

`usePlayer()` with no selector returns the store without subscribing, so `const { paused } = usePlayer()` never re-renders. Always pass a selector for values you render. The preset’s `usePlayer` from `@videojs/react/video` is typed to the preset’s features; [`createPlayer`](https://videojs.org/docs/framework/react/reference/api/create-player) returns a typed pair for a custom feature list.

`VideoPlayer` renders no DOM, so wrapping more of your page in it is free. That replaces the ref you passed to `useMediaState` to read state from outside the player.

### Drive playback

Vidstack’s remote control dispatched request events that the player satisfied. Video.js actions call the media directly. They aren’t queued, so most fail until the player has attached to its media, `seek()` included; once attached, `seek()` waits for metadata. Their promises reject where Vidstack fired `play-fail` or `fullscreen-error`.

| Vidstack | Video.js 10 action |
| --- | --- |
| `play()`, `pause()`, `togglePaused()` | `play()`, `pause()` |
| `seek(time)` | `seek(time)` |
| `seekToLiveEdge()` | Use `LiveButton`, or seek to the end of the last `seekable` range |
| `changeVolume(volume)` | `setVolume(volume)`; a value above 0 also unmutes |
| `mute()`, `unmute()`, `toggleMuted()` | `setMuted(muted)` |
| `changePlaybackRate(rate)` | `setPlaybackRate(rate)` |
| `enterFullscreen(target)`, `exitFullscreen()`, `toggleFullscreen()` | `requestFullscreen()`, `exitFullscreen()`; there’s no target |
| `enterPictureInPicture()`, `exitPictureInPicture()`, `togglePictureInPicture()` | `requestPictureInPicture()`, `exitPictureInPicture()` |
| `toggleCaptions()`, `showCaptions()`, `disableCaptions()` | `toggleSubtitles()`, `toggleSubtitles(true)`, `toggleSubtitles(false)` |
| `changeTextTrackMode(index, mode)` | `selectSubtitlesTrack(id)`, or `selectSubtitlesTrack(null)` to turn them off |
| `changeQuality(index)`, `requestAutoQuality()` | `selectVideoRendition(id)`, `selectVideoRendition('auto')` |
| `changeAudioTrack(index)` | `selectAudioTrack(id)` |
| `pauseControls()`, `resumeControls()` | `requestControlsLock()`, which returns a release function |
| `toggleControls()` | `toggleControls()` |
| `requestAirPlay()`, `requestGoogleCast()` | `promptRemotePlayback()` |
| `startLoading()`, `startLoadingPoster()`, `changeDuration()`, `changeClipStart()`, `changeAudioGain()`, `seeking()` | No equivalent |

The store has no toggles apart from `toggleSubtitles()` and `toggleControls()`, so call the pair you need, as in `paused ? play() : pause()`. Hotkeys and gestures keep the toggle names, so `togglePaused` still works as their action.

Vidstack methods took an optional trigger event as their last argument. Video.js actions don’t, so wrap them in a handler, as in `onClick={() => seek(30)}`. Passing an action straight to `onClick` would hand it the click event.

Where you called `play()` or set `currentTime` through a `MediaPlayerInstance` ref, pass `mediaRef` to the media component instead. It receives the element for `Video` and `Audio`, and the playback adapter for `HlsJsVideo`, embeds, and other adapter-backed media. That’s the same object `useMedia()` returns:

```tsx
import type { HlsJsAdapter } from '@videojs/hlsjs-video';

const mediaRef = useRef<HlsJsAdapter>(null);

<HlsJsVideo mediaRef={mediaRef} src="https://example.com/stream.m3u8" />

// In an event handler
mediaRef.current?.play();
```

State keys follow the same pattern. The common renames:

| Vidstack | Video.js 10 |
| --- | --- |
| `canFullscreen`, `canPictureInPicture`, `canSetVolume` | `fullscreenAvailability`, `pictureInPictureAvailability`, `volumeAvailability` |
| `fullscreen`, `pictureInPicture` | `isFullscreen`, `isPictureInPicture` |
| `canAirPlay`, `canGoogleCast` | `remotePlaybackAvailability` |
| `qualities`, `quality`, `autoQuality` | `videoRenditionList`, `activeVideoRendition`; auto is on when no rendition is `selected` |
| `audioTracks`, `audioTrack` | `audioTrackList`, the entry with `enabled` |
| `textTracks`, `textTrack` | `textTrackList`, the caption or subtitle entry with `mode: 'showing'`; `subtitlesShowing` says whether there is one |
| `buffered`, `seekable` | The same names, as arrays of `[start, end]` pairs |
| `live`, `liveEdge`, `userBehindLiveEdge` | `targetLiveWindow` and `liveEdgeStart`, in the live presets; `LiveButton` computes the live edge |
| `streamType` | `streamType`, once you add `streamTypeFeature`; only `live`, `on-demand`, and `unknown` |
| `playing`, `canSeek`, `autoPlayError`, `mediaType`, `viewType`, `orientation`, `pointer`, `width`, `height` | No store key |

Two keys behave differently. `started` can turn off again after the media is reset or sits paused at the start, and `currentTime` follows native `timeupdate`, about four times a second, where Vidstack updated it every animation frame.

### Events

Vidstack fired a normalized set of events on `<media-player>`, including state-change events such as `fullscreen-change` and `controls-change`. Video.js fires no player events of its own.

Put standard media event props on the media component: `onPlay`, `onCanPlay`, `onTimeUpdate`, `onEnded`, and so on. They receive React’s synthetic event on media that renders a `<video>`, and a plain `Event` on the embeds, where Vidstack’s callbacks received a detail and the event. The embeds route the same prop names. For anything that isn’t a media event, read the state:

```tsx
// Vidstack
<MediaPlayer onFullscreenChange={(isFullscreen) => track(isFullscreen)} />

// Video.js 10
function FullscreenTracker() {
  const isFullscreen = usePlayer((state) => state.isFullscreen);
  // Unlike onFullscreenChange, this also runs once on mount.
  useEffect(() => track(isFullscreen), [isFullscreen]);
  return null;
}
```

| Vidstack event | Video.js 10 |
| --- | --- |
| `can-play`, `loaded-metadata`, `time-update`, `duration-change`, `volume-change`, `rate-change` | `canplay`, `loadedmetadata`, `timeupdate`, `durationchange`, `volumechange`, `ratechange` on the media |
| `fullscreen-change`, `picture-in-picture-change`, `controls-change`, `remote-playback-change` | The `isFullscreen`, `isPictureInPicture`, `controlsVisible`, and `remotePlaybackState` state |
| `quality-change`, `audio-track-change`, `text-track-change` | The `activeVideoRendition`, `audioTrackList`, and `textTrackList` state |
| `provider-change`, `provider-setup` | The media’s `source`, and its `engine` |
| `play-fail`, `fullscreen-error`, `picture-in-picture-error` | A rejected action promise |
| `auto-play-fail` | No event; see [Autoplay](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#autoplay) |
| `media-*-request` | No equivalent |
| `replay`, `end`, `destroy`, `stream-type-change`, `orientation-change` | No equivalent |

Event triggers, `originEvent`, and `isOriginTrusted` have no equivalent. Check `event.isTrusted` in your own handler before calling an action if you need to know a person started it.

## Captions, chapters, and thumbnails

### Captions

Caption `<track>` elements move from `<media-provider>` to the media. Video.js reads captions and subtitles from those tracks and from streaming manifests.

The browser parses and renders the cues, so:

- **Only WebVTT works.** Vidstack parsed SRT, SSA/ASS, and JSON with `type` ([#3037](https://github.com/videojs/v10/issues/3037)). Convert them to WebVTT at build time or on your server.
- **Style captions with `::cue`.** `<media-captions>`, its `data-part` selectors, and the `--media-cue-*` variables have no equivalent ([#3038](https://github.com/videojs/v10/issues/3038)). The skins keep native captions clear of the controls in Chromium and WebKit browsers.
- **There’s no caption style menu** for viewers to pick fonts, colors, and backgrounds ([#1437](https://github.com/videojs/v10/issues/1437)). Viewers can still set caption preferences in their operating system or browser.
- **Adding tracks from code is native.** `textTracks.add()` becomes a `<track>` element, or `addTextTrack()` and `VTTCue` on a plain `<video>`.

The captions toggle picks a track differently. Vidstack restored the last track shown, then the `default` track, then the first one. Video.js restores the last track shown, then one that matches the browser’s language, then the first track. See [Captions](https://videojs.org/docs/framework/react/guides/captions).

### Chapters

A `<track kind="chapters" default>` still segments the time slider, and the chapter under the pointer shows in the preview. Vidstack’s chapters menu, `ChapterTitle` outside the slider, and `useChapterOptions` have no equivalent ([#1873](https://github.com/videojs/v10/issues/1873)). To add chapters from code, use the native track APIs described under [Captions](https://videojs.org/docs/framework/react/guides/migrate-from-vidstack#captions); there’s no dedicated chapters API yet ([#1268](https://github.com/videojs/v10/issues/1268)). For a current-chapter label elsewhere, find the cue in the `chaptersCues` state that contains `currentTime`.

### Thumbnails

The `thumbnails` layout prop and `Thumbnail`’s `src` become a track on the media, and the skin picks it up:

```tsx
<Video src="/video.mp4" crossOrigin="anonymous">
  <track kind="metadata" label="thumbnails" src="https://cdn.example.com/storyboard.vtt" default />
</Video>
```

`default` is required, or the cues never load. Set `crossOrigin` on the media when the storyboard comes from another origin. A cross-origin track only loads in CORS mode, and the thumbnail images load in the same mode, so their host needs CORS headers too. Vidstack also accepted JSON and Mux `storyboard.json` URLs ([#3044](https://github.com/videojs/v10/issues/3044)); fetch and convert those yourself and pass the result to the `thumbnails` prop on `Thumbnail.Root`, or use `MuxVideo`, which adds the storyboard track for you. See [Thumbnails](https://videojs.org/docs/framework/react/guides/thumbnails).

## Keyboard shortcuts and gestures

### Keyboard shortcuts

The packaged video skins ship a default set close to Vidstack’s: Space and `k` to play, `m` to mute, `f` for fullscreen, `c` for captions, `i` for picture-in-picture, arrow keys and `j`/`l` to seek and change volume, `0`–`9` to jump, and `<`/`>` for speed. They also add Home and End. The live skins leave out seeking, jumping, Home and End, and speed, and the audio skins leave out `f`, `c`, and `i`.

Two defaults differ. Seeking moves 10 seconds with or without Shift, where Vidstack’s Default Layout moved 10 seconds, or 20 with Shift. And the speed keys step through the fixed rate list and wrap around instead of moving by 0.25.

The `keyShortcuts` prop becomes one hotkey per shortcut in a layout you compose or in skin source. Each takes a single key pattern, so `togglePaused: 'k Space'` becomes two hotkeys:

```tsx
// Vidstack
<MediaPlayer keyShortcuts={{ togglePaused: 'k Space', seekBackward: 'ArrowLeft', seekForward: 'ArrowRight' }} />

// Video.js 10, inside a Container
<Hotkey keys="k" action="togglePaused" />
<Hotkey keys="Space" action="togglePaused" />
<Hotkey keys="ArrowLeft" action="seekStep" value={-5} />
<Hotkey keys="ArrowRight" action="seekStep" value={5} />
```

Shortcuts with custom callbacks become the `useHotkey` hook: `useHotkey({ keys: 'n', onActivate: playNext })`.

| Vidstack action | Video.js 10 action |
| --- | --- |
| `togglePaused`, `toggleMuted`, `toggleFullscreen`, `togglePictureInPicture` | Same names |
| `toggleCaptions` | `toggleSubtitles` |
| `seekBackward`, `seekForward` | `seekStep` with a negative or positive `value` in seconds |
| `volumeDown`, `volumeUp` | `volumeStep` with a negative or positive `value` |
| `speedUp`, `slowDown` | `speedUp`, `speedDown` |
| Digit keys | `keys="0-9"` with `seekToPercent` |

`keyTarget="document"` becomes `target="document"` on each hotkey. With several players on a page, the first one registered handles the key; Vidstack sent it to the last player you used. `keyDisabled` has no player-wide switch, and packaged skins always include their hotkeys, so remove them in skin source. A tooltip’s `Shortcut` part shows the key bound to its button, and buttons set `aria-keyshortcuts` from the registered hotkeys. Writing `aria-keyshortcuts` yourself no longer creates a shortcut. See [Keyboard shortcuts](https://videojs.org/docs/framework/react/guides/keyboard-shortcuts).

### Gestures

Vidstack’s gestures listened for any DOM event and took their hit area from their own box. Video.js gestures recognize taps and double taps, divide the player into regions, and can be limited to one pointer type:

| Vidstack | Video.js 10 |
| --- | --- |
| `event="pointerup" action="toggle:paused"` | `type="tap" action="togglePaused" pointer="mouse"` |
| `event="pointerup" action="toggle:controls"` | `type="tap" action="toggleControls" pointer="touch"` |
| `event="dblpointerup" action="toggle:fullscreen"` | `type="doubletap" action="toggleFullscreen" region="center"` |
| `event="dblpointerup" action="seek:-10"` on the left edge | `type="doubletap" action="seekStep" value="-10" region="left"` |
| `event="dblpointerup" action="seek:10"` on the right edge | `type="doubletap" action="seekStep" value="10" region="right"` |
| Other events, such as `mouseleave` | No equivalent |
| `will-trigger` and `trigger` events | Use `useTapGesture` or `useDoubleTapGesture` in React, or `createTapGesture` and `createDoubleTapGesture` in HTML, and decide in the callback |

The packaged video skins already bind these defaults. Vidstack’s swipe-to-scrub gesture has no equivalent ([#3046](https://github.com/videojs/v10/issues/3046)).

## Fullscreen and orientation

Fullscreen targets the skin’s container, falling back to the video element on iPhone. There’s no `target` option; to take only the video fullscreen, call the native method on it yourself.

Vidstack locked the screen to landscape in fullscreen by default. Video.js presets don’t. Add `orientationLockFeature` to a player built with [`createPlayer`](https://videojs.org/docs/framework/react/guides/fullscreen) to lock it again. Turning Vidstack’s fullscreen orientation off just means leaving the feature out. Vidstack’s screen orientation state and `lockScreenOrientation()` have no equivalent; use `screen.orientation`.

## Live streams

Vidstack switched the Default Layout to live controls by `streamType`. Video.js has separate live presets, whose skins show a live button and no time slider:

```tsx
import '@videojs/react/live-video/skin.css';
import { LiveVideoPlayer, LiveVideoSkin } from '@videojs/react/live-video';
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';

<LiveVideoPlayer>
  <LiveVideoSkin>
    <HlsJsVideo src="/live.m3u8" playsInline />
  </LiveVideoSkin>
</LiveVideoPlayer>
```

- **DVR comes from the stream.** `live:dvr` becomes `targetLiveWindow === Infinity`, which the media reports for event playlists. There’s no way to force DVR on a sliding window. Add a time slider in skin source to let viewers seek.
- **The live edge moved to the live button.** `liveEdge`, `userBehindLiveEdge`, and `seekToLiveEdge()` become the live button’s state and behavior. It counts playback as live within 5 seconds of the stream’s live edge start, which already sits behind the seekable end by the playlist’s hold-back. Vidstack counted the last `liveEdgeTolerance` seconds before the seekable end, 10 by default and configurable ([#1730](https://github.com/videojs/v10/issues/1730)).
- **`streamType` needs a feature.** No preset includes `streamTypeFeature`; add it to a custom player when one player switches between live and on-demand UI.
- **Live presets are narrower.** They leave out playback rate, quality, and audio-track state. Build a player from a feature list to add them back.

See [Live streams](https://videojs.org/docs/framework/react/guides/live-streams).

## AirPlay and Google Cast

The video skins include AirPlay and Cast buttons. Both call one action, `promptRemotePlayback()`, and each button shows only on the platform that supports it. Without the Google Cast extension, the Cast button uses the browser’s Remote Playback API.

Vidstack’s `googleCast` prop becomes the `GoogleCast` extension, placed anywhere inside the player:

```tsx
import { GoogleCast } from '@videojs/react/extensions/google-cast';

<VideoPlayer>
  <VideoSkin>
    <HlsJsVideo src="/stream.m3u8" playsInline />
    <GoogleCast receiver="YOUR_RECEIVER_ID" />
  </VideoSkin>
</VideoPlayer>
```

Only the receiver ID carries over from Vidstack’s Cast options, and the Cast prompt events have no equivalent ([#3048](https://github.com/videojs/v10/issues/3048)). There’s no device name or `remotePlaybackType` either ([#3047](https://github.com/videojs/v10/issues/3047)). See [Cast to AirPlay and Chromecast](https://videojs.org/docs/framework/react/guides/casting).

## Languages

Vidstack layouts took a `translations` object keyed by English strings, and you supplied every language yourself. Video.js ships locale packs for around 50 languages. Wrap the player in the i18n provider and it loads the pack for the nearest `lang` attribute; without one, the controls use English. Override strings with namespaced keys:

```tsx
// Vidstack
<DefaultVideoLayout translations={{ Play: 'Start video', Settings: 'Options' }} />

// Video.js 10
import { I18nProvider } from '@videojs/react/i18n';

<I18nProvider translations={{ buttons: { play: 'Start video' }, menu: { settings: 'Options' } }}>
  {/* … */}
</I18nProvider>
```

Strings for the chapters menu, caption styles, audio boost, and download button have no keys, because those features don’t exist yet. See [Internationalize the player](https://videojs.org/docs/framework/react/guides/internationalization) for the full key list.

## Preferences and autoplay

### Saved preferences

Vidstack’s `storage` saved volume, mute, captions, language, playback rate, quality, audio gain, and playback position. Video.js doesn’t save anything between visits yet ([#944](https://github.com/videojs/v10/issues/944)). [Remember user preferences](https://videojs.org/docs/framework/react/guides/user-preferences) shows how to restore and save volume and caption choices yourself.

### Autoplay

Move `autoPlay` from `MediaPlayer` to the media component, along with `muted` and `playsInline`. There’s no `auto-play-fail` event or `autoPlayError` state; a blocked autoplay looks like media that never started. To react to it, leave out `autoPlay`, call `play()` once the player attaches, and catch the rejection. See [Autoplay](https://videojs.org/docs/framework/react/guides/autoplay).

## Behavior changes to check

These changes don’t throw errors, so test for them:

- **Loading.** Media loads as soon as it attaches, not when the player scrolls into view, and embeds don’t preconnect.
- **Size.** There’s no default 16:9 box; set `aspect-ratio` on the skin.
- **Fullscreen.** Presets don’t lock the screen to landscape, and media that isn’t set to play inline no longer enters fullscreen when it starts on Android and iPad. iPhone Safari still plays it fullscreen natively.
- **Controls.** They hide as soon as the pointer leaves the player during playback, where Vidstack waited for its 2-second idle delay.
- **Hotkeys.** Shift no longer doubles the 10-second seek step, and the speed keys wrap around a fixed list.
- **Captions.** The captions toggle prefers the browser’s language over the `default` track.
- **Embeds.** YouTube URLs and Vimeo no longer use their privacy-enhanced modes by default; `youtube/ID` shorthands still do.
- **Time.** `currentTime` updates about four times a second instead of every frame.
- **Live.** Playback counts as live within 5 seconds of the stream’s live edge start, not 10 seconds of the seekable end, and live skins have no time slider, quality, audio track, or rate menu.
- **Volume.** `setVolume()` above 0 also unmutes, and unmuting at 0 restores 25%. Vidstack’s controls did the same, but setting its `volume` or `muted` properties didn’t.
- **System integration.** Nothing is saved between visits, and Video.js doesn’t set Media Session metadata for lock screens and hardware keys.
- **Tooltips.** They open after 600 ms instead of 700 ms.

## Known gaps

Ordered roughly by how likely each is to block a Vidstack migration. Follow [Vidstack Parity](https://github.com/videojs/v10/issues/3035) for progress.

- **No automatic provider selection.** `resolveAdapterType` tells you which media component plays a URL, but you render it yourself ([#2160](https://github.com/videojs/v10/issues/2160)).
- **Nothing persists** between visits: volume, captions, language, rate, quality, or position ([#944](https://github.com/videojs/v10/issues/944)).
- **No caption style settings** ([#1437](https://github.com/videojs/v10/issues/1437)), no custom caption renderer ([#3038](https://github.com/videojs/v10/issues/3038)), and WebVTT only: no SRT, SSA/ASS, or JSON captions ([#3037](https://github.com/videojs/v10/issues/3037)). Audio players don’t show captions ([#3039](https://github.com/videojs/v10/issues/3039)).
- **No chapters menu** or chapter title outside the time slider ([#1873](https://github.com/videojs/v10/issues/1873)), and no dedicated API for chapters from code ([#1268](https://github.com/videojs/v10/issues/1268)). Cue points and markers aren’t implemented ([#1442](https://github.com/videojs/v10/issues/1442)).
- **Fixed playback rates**: `0.2`, `0.5`, `0.7`, `1`, `1.2`, `1.5`, `1.7`, `2` ([#1404](https://github.com/videojs/v10/issues/1404)). No speed or quality sliders ([#3052](https://github.com/videojs/v10/issues/3052)).
- **No audio gain or boost** ([#1135](https://github.com/videojs/v10/issues/1135)).
- **No load strategies.** Vidstack’s media and poster loading strategies and `startLoading()` have no equivalent ([#3043](https://github.com/videojs/v10/issues/3043)), and embeds don’t preconnect ([#1433](https://github.com/videojs/v10/issues/1433)).
- **No clipping.** Vidstack’s clip start and end times have no equivalent ([#3040](https://github.com/videojs/v10/issues/3040)).
- **No download button** ([#3041](https://github.com/videojs/v10/issues/3041)).
- **No Remotion provider** or Remotion components ([#3053](https://github.com/videojs/v10/issues/3053)).
- **No Media Session** metadata from `title`, `artist`, and `artwork` ([#3042](https://github.com/videojs/v10/issues/3042)).
- **Fixed timing.** The controls hide delay ([#1728](https://github.com/videojs/v10/issues/1728)) and the live edge tolerance ([#1730](https://github.com/videojs/v10/issues/1730)) aren’t configurable, and there’s no duration override ([#1729](https://github.com/videojs/v10/issues/1729)).
- **No debug logging** to replace Vidstack’s log level ([#1406](https://github.com/videojs/v10/issues/1406)).
- **Fewer embed conveniences.** No automatic embed posters ([#3049](https://github.com/videojs/v10/issues/3049)), Vimeo chapters ([#3050](https://github.com/videojs/v10/issues/3050)), or Vimeo quality selection ([#3051](https://github.com/videojs/v10/issues/3051)).
- **Less remote playback detail.** No route type or device name ([#3047](https://github.com/videojs/v10/issues/3047)), and no Cast prompt events or Cast options beyond the receiver ID ([#3048](https://github.com/videojs/v10/issues/3048)).
- **Fewer time slider and gesture extras.** No video preview in the time slider ([#3045](https://github.com/videojs/v10/issues/3045)), JSON thumbnail storyboards ([#3044](https://github.com/videojs/v10/issues/3044)), or swipe to scrub ([#3046](https://github.com/videojs/v10/issues/3046)).
- **No request events**, event triggers, or ways to cancel a request, by design.
- **No light theme for video skins** ([#3054](https://github.com/videojs/v10/issues/3054)), no Plyr-style skin ([#181](https://github.com/videojs/v10/issues/181)), and no Tailwind skin source for HTML ([#3055](https://github.com/videojs/v10/issues/3055)).
- **No ads** ([#3056](https://github.com/videojs/v10/issues/3056)), which are on the roadmap for late 2026.

## See also

- [Build with AI](https://videojs.org/docs/framework/react/guides/build-with-ai)
- [Features](https://videojs.org/docs/framework/react/guides/features) and [Presets](https://videojs.org/docs/framework/react/guides/presets)
- [Media sources](https://videojs.org/docs/framework/react/guides/media-sources)
- [Skins](https://videojs.org/docs/framework/react/guides/skins) and [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins)
- [Migrate from Plyr](https://videojs.org/docs/framework/react/guides/migrate-from-plyr)