Migrate from Media Chrome

Video.js v10’s HTML player uses the same media-* custom-element convention as Media Chrome, so most of the work is renaming and reshaping, not rewriting. This guide maps Media Chrome’s API to Video.js v10.

Before you begin

Install Video.js and pick a preset and skin (see Installation). The fastest path is to start from a preset, then replace its controls with your migrated markup.

npm install @videojs/html

npm install @videojs/react

Map the controller

Media Chrome wraps a slotted <video slot="media"> in a single <media-controller>. Video.js splits that into two elements. The player owns state and draws nothing. The <media-container> is the box everything lives in, with the media as a plain child.

<!-- Media Chrome -->
<media-controller>
  <video slot="media" src="video.m3u8"></video>
  <media-control-bar>
    <media-play-button></media-play-button>
  </media-control-bar>
</media-controller>

<!-- Video.js -->
<video-player>
  <media-container>
    <video src="video.mp4"></video>
    <media-controls>
      <media-play-button></media-play-button>
    </media-controls>
  </media-container>
</video-player>

'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 />
      </Container>
    </VideoPlayer>
  );
}

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

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

<PlayButton
  render={(props, state) => (
    <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>
  )}
/>

Map controller attributes

Media Chrome configures behavior through <media-controller> attributes. Video.js v10 has no single controller element, 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.
• <media-container> and <media-controls> — layout, focus, and autohide.
• Dedicated elements — <media-hotkey>, <media-gesture>, and friends, declared in markup.

Hotkeys

Media Chrome toggles keyboard shortcuts with nohotkeys and hotkeys. Video.js declares each shortcut as its own element, so you opt in to exactly the keys you want and set seek offsets inline:

<media-hotkey keys="Space" action="togglePaused"></media-hotkey>
<media-hotkey keys="m" action="toggleMuted"></media-hotkey>
<media-hotkey keys="ArrowRight" action="seekStep" value="5"></media-hotkey>
<media-hotkey keys="ArrowLeft" action="seekStep" value="-5"></media-hotkey>

To drop a shortcut, remove its element or add disabled. There’s no global “all hotkeys off” switch; omit the elements you don’t need.

Gestures

gesturesdisabled becomes per-element <media-gesture> controls. Tap and double-tap behavior — click to toggle play, double-tap to seek or go fullscreen — is declared explicitly:

<media-gesture type="tap" action="togglePaused" pointer="mouse" region="center"></media-gesture>
<media-gesture type="doubletap" action="seekStep" value="-10" region="left"></media-gesture>
<media-gesture type="doubletap" action="seekStep" value="10" region="right"></media-gesture>

Remove an element or set disabled to turn a gesture off.

Map the elements

Most names match. These are the renames that bite:

Unchanged names: media-play-button, media-mute-button, media-fullscreen-button, media-pip-button, media-airplay-button, media-cast-button, media-captions-button, media-playback-rate-button, media-tooltip, and media-thumbnail.

Sliders are compound in both, using media-slider-track, media-slider-fill, and media-slider-thumb.

<media-poster>
  <img src="/poster.jpg" alt="" decoding="async" />
</media-poster>

<Poster src="/poster.jpg" alt="" />

Rewrite your styles

Media Chrome reflects state as media* attributes such as mediapaused; Video.js uses data-*.

/* Media Chrome */
media-play-button[mediapaused] .play-icon { display: inline; }

/* Video.js */
media-play-button[data-paused] .play-icon { display: inline; }

Continuous values use CSS custom properties: sliders expose --media-slider-fill and --media-slider-pointer.

Themes become skins

Media Chrome’s <template>-based themes (media-theme) become Video.js skins and presets. Start from a preset, then eject and customize with Customize skins, rather than authoring a template.

Known gaps

These Media Chrome features have no direct equivalent yet. Several can be approximated; see Workarounds.

• No configurable autohide delay or disable switch (autohide="-1"), and no autohideovercontrols (#1728)
• No defaultduration placeholder before the media loads (#1729)
• No preference persistence, so Media Chrome’s novolumepref, nomutedpref, and nosubtitleslangpref opt-outs have nothing to opt out of. Persistence is out of scope for GA; tracked at #944, with subtitle language at #1423
• 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)
• Chapters render, but there’s no active-chapter state, no chapterchange event, and no menu to jump between them (#1873)
• Cue points are not supported (#1442)

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 media-time-slider-chapters and media-time-slider-chapter-title.

Workarounds

Disable autohide (autohide="-1")

The skin hides controls by removing data-visible from the root <media-controls>. Which element then fades depends on the player’s width: below 32rem it’s the --primary and --secondary groups inside the root, and at or above 32rem it’s the root itself. Override both, plus the hidden cursor, in your player CSS:

.media-default-skin--video .media-controls--root:not([data-visible]) {
  opacity: 1;
  scale: 1;
  filter: none;
  pointer-events: auto;

  .media-controls--primary,
  .media-controls--secondary {
    opacity: 1;
    scale: 1;
    filter: none;
    pointer-events: auto;
  }
}

.media-default-skin--video:has(.media-controls--root:not([data-visible])) {
  cursor: auto;
}

Two things make this fragile. It matches the skin’s own selectors exactly, so it only wins on source order — load your stylesheet after the skin’s. And the class names are the default skin’s; the minimal skin fades .media-minimal-skin--video .media-controls instead, with no groups to reach.

To change the delay rather than disable it, note that the idle timer is a constant inside controlsFeature. Fork that feature, swap it into a custom feature list, and pass that list to createPlayer:

const features = videoFeatures.map((f) => (f.name === 'controls' ? myControlsFeature : f));

Breakpoints

The skin root is an inline-size container named media-root, so write responsive styles with container queries instead of breakpoints attributes. This is exactly how the built-in skins adapt:

@container media-root (width > 40rem) {
  .media-controls { /* wide layout */ }
}

Default duration

There’s no player input for a pre-load duration. Use preload="metadata", the default, so the real duration is known almost immediately; only preload="none" defers it. If you must defer loading, render your own static placeholder in markup.

Preference persistence

Media Chrome remembers volume, muted state, and language across sessions. Video.js v10 persists nothing, so restore and save the values yourself.

import { selectVolume, usePlayer } from '@videojs/react';
import { useEffect } from 'react';

function PersistVolume() {
  const volume = usePlayer(selectVolume);

  useEffect(() => {
    const saved = localStorage.getItem('vjs:volume');
    if (saved) volume.setVolume(Number(saved));
  }, []);

  useEffect(() => {
    localStorage.setItem('vjs:volume', String(volume.volume));
  }, [volume.volume]);

  return null;
}

Live edge offsets

seektoliveoffset and noautoseektolive are governed by the playback engine rather than the UI layer, so there’s no attribute to tune them today. The escape hatch is a custom live control built against the selectLive and selectTime player state.

See also

• Installation
• UI components
• Skins and Customize skins