Migrate from Media Chrome

Video.js v10’s React components mirror Media Chrome’s elements — media-play-button becomes PlayButton — so most of the work is renaming and reshaping, not rewriting.

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 draws nothing. The container is the box everything lives in, with the media as a plain child.

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

'use client';

import { Container, PlayButton } from '@videojs/react';
import { Video, VideoPlayer } from '@videojs/react/video';

export function MyPlayer() {
  return (
    <VideoPlayer>
      <Container>
        <Video src="video.mp4" />
        <PlayButton
          render={(props, state) => (
            <button {...props} className="play-button">
              {state.paused ? <span className="play-icon">Play</span> : <span className="pause-icon">Pause</span>}
            </button>
          )}
        />
      </Container>
    </VideoPlayer>
  );
}

A preset player carries a fixed set of features. When you need a different set, build your own with createPlayer. Hand it a feature list and you get back a typed Player component and usePlayer hook, the same pair the preset is made of. Call it once, outside your component, and reuse it.

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 in the same component that returns the provider is still outside that provider.

Media Chrome configures behavior through <media-controller> attributes. Video.js v10 has no single controller component, so these settle into three places:

• Player features — playback behavior that comes from the player’s feature set. A preset picks one for you; createPlayer lets you name your own.
• Container and Controls — layout, focus, and autohide.
• Dedicated components — Hotkey, Gesture, and friends, rendered inside the player.

Media Chrome 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} />

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.

gesturesdisabled becomes per-component Gesture controls. Tap and double-tap behavior — click to toggle play, double-tap to seek or go fullscreen — is declared explicitly:

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" />

Remove a component or pass disabled to turn a gesture off.

Most names carry over as PascalCase components without the media- prefix. These are the renames that bite:

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 is the one rename that changes shape. Put the poster URL on VideoPlayer; Poster.Root owns its state and Poster.Image accepts image attributes such as alt, srcSet, and sizes:

<VideoPlayer poster="/poster.jpg">
  <Container>
    <Poster.Root>
      <Poster.Image alt="" />
    </Poster.Root>
  </Container>
</VideoPlayer>

React skins do not use Shadow DOM. Use render props when you build individual controls. Add the files for a ready-made skin when you need to change its control set or layout.

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

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

function FullscreenShortcut() {
  const toggleFullscreen = usePlayer((state) => state.toggleFullscreen);
  // Call toggleFullscreen() from your own UI.
  return null;
}

Put a ref on the media component to reach the rendered HTMLVideoElement; there’s no media slot to reach through. For the Video.js media object, call useMedia from a component inside the player; media that wrap a playback engine expose it there through the engine escape hatch.

Chapters themselves do work. Add a default <track kind="chapters"> and the packaged skins segment the time slider and show the chapter title on hover, via TimeSlider.Chapters and TimeSlider.ChapterTitle.

Set visibility="always" on Controls.Root and the controls stay visible regardless of activity. Packaged skins don’t expose that prop; to keep a preset skin’s look, add the skin source to your project and set it on the skin’s controls component rather than overriding private selectors.