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.

Before you begin

Install Video.js and choose a preset (see Installation). Start with its ready-made skin if those controls fit your player. If you need to keep a custom control bar, build it from the individual Video.js UI components instead.

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>

import '@videojs/html/video/player';
import '@videojs/html/ui/controls';
import '@videojs/html/ui/play-button';
import '@videojs/html/icons/element';

<!-- Video.js -->
<video-player>
  <media-container>
    <video src="video.mp4"></video>
    <media-controls>
      <media-controls-content>
        <media-play-button class="player-play-button">
          <media-icon class="player-play-icon" name="play"></media-icon>
          <media-icon class="player-pause-icon" name="pause"></media-icon>
        </media-play-button>
      </media-controls-content>
    </media-controls>
  </media-container>
</video-player>

.player-pause-icon {
  display: none;
}

.player-play-button:defined:not([data-paused]) .player-play-icon {
  display: none;
}

.player-play-button:defined:not([data-paused]) .player-pause-icon {
  display: inline-flex;
}

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

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

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

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.

Video.js sliders use media-slider-track, media-slider-fill, and media-slider-thumb. See media-time-slider and media-volume-slider for copy-paste markup and CSS.

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

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

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 HTML */
media-play-button[data-paused] .play-icon { display: inline; }

/* Video.js React: target the className on your rendered button */
.play-button[data-paused] .play-icon { display: inline; }

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

Map theme variables by meaning

Media Chrome and Video.js both use names beginning with --media-, but that shared prefix is a naming convention, not a compatibility layer. Keep a variable only when its documented meaning matches.

The packaged Video.js skins expose --media-accent-color, --media-accent-text-color, --media-border-radius, and --media-scale-unit for broad customization. Do not assume another Media Chrome variable will work because its name starts with --media-.

Themes become skins

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

Control the player imperatively

Control everything through the player’s store. Media Chrome had no player object; Video.js gives you one, with an action for every operation — play, togglePaused, seek, setVolume, toggleFullscreen — so one mental model covers playback and the state the browser doesn’t own, such as fullscreen, captions, and quality.

const player = document.querySelector('video-player');

player.store.state.toggleFullscreen();

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

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

The Media Chrome habit of scripting the media element directly still works, unchanged. The media is a plain child of the player, and Video.js derives player state from the native media events, so video.play() or video.currentTime = 30 never leaves the controls out of sync. The media element also stays the way to swap src, replace the media component, and listen for native events.

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)
• 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). Video.js can choose an initial subtitle track from the locale, but it does not yet remember the viewer’s later language choice (#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)
• Chapters render and each time-slider segment reflects data-active, but there’s no player-level active chapter value, chapterchange event, or menu to jump between them (#1873)
• 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")

Packaged skins don’t expose an autohide switch. Install the closest skin’s source and remove its hidden-control styles. That’s safer than overriding internal selectors in a skin you don’t own.

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, useState } from 'react';

function PersistVolume() {
  const volume = usePlayer(selectVolume);
  const [readyToSave, setReadyToSave] = useState(false);

  useEffect(() => {
    const saved = localStorage.getItem('vjs:volume');
    if (saved !== null) {
      const savedVolume = Number(saved);
      if (Number.isFinite(savedVolume)) volume.setVolume(savedVolume);
    }
    setReadyToSave(true);
  }, []);

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

  return null;
}

Live edge offsets

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

See also

• Installation
• UI components
• Skins and Customize skins