Migrate from Media Chrome

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.

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.

Media Chrome’s React package wraps its custom elements. @videojs/react ships native components instead. VideoPlayer comes from the video preset, and Container holds the media and controls:

'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:

.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. For a custom set, call createPlayer once outside your React component. Pass it the feature list, then use the Player component and typed usePlayer hook it returns.

import { createPlayer } from '@videojs/react';
import { videoFeatures } from '@videojs/react/video';

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

Read player state with usePlayer, useMedia, and useStore. 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.

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

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.

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:

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.

Most names carry over as PascalCase components without the media- prefix. Start with these name changes:

Unchanged names, in PascalCase: PlayButton, MuteButton, FullscreenButton, PiPButton, AirPlayButton, CastButton, CaptionsButton, PlaybackRateButton, Tooltip, and Thumbnail.

React buttons do not include visible content either. Use a button’s render prop to add it, as shown in 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 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:

import { Poster } from '@videojs/react';

<Poster.Root>
  <Poster.Image alt="" />
</Poster.Root>

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.

Select an action with the same usePlayer hook you read state with:

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

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.

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.

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 and set visibility="always" on its controls component.