Migrate from Media Chrome

Replace Media Chrome’s controller with a Video.js player and container, then migrate your controls. The libraries share media-* tag names, but their attributes, child markup, icons, and styles differ.

Before loading Video.js HTML, remove every Media Chrome import and CDN script from the page, including any that another component loads. Then reload the page. Both libraries register custom elements with names such as media-play-button. A document can hold only one definition per name, and Video.js keeps any definition that already exists. If you need both libraries during migration, load them in separate documents, such as an iframe.

For a page without a bundler, load the CDN video preset. It registers the player, the UI elements and icons used in the controller example below, and the <media-i18n> element:

<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/video.js"></script>

Some elements in the mapping table below need separate bundles. If you use any of these elements, also load its bundle:

• media-seek-button: https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/ui/seek-button.js
• media-playback-rate-button: https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/ui/playback-rate-button.js
• media-thumbnail: https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/ui/thumbnail.js

Load each with <script type="module" src="…"></script>. See CDN for individual component bundles.

For a bundler installation:

npm install @videojs/html

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 renders no UI. The <media-container> holds the media and controls. Put the media directly inside the container.

Use the HTML and CSS tabs for both installation methods. With a bundler, also add the JavaScript imports. With the CDN video preset, skip those imports because the preset already registers these elements.

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

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

.app-player-container {
  position: relative;
  display: block;
  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;
}

.player-play-button media-icon {
  display: inline-flex;
  width: 1.5rem;
  height: 1.5rem;
}

.player-play-button .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;
}

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

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>

In a custom layout, put these elements inside the player’s <media-container>. With installed skin source, edit its existing hotkey declarations.

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.

Declare each tap or double-tap behavior with a <media-gesture> element. For example, declare a tap that toggles playback, or a double-tap that seeks or enters fullscreen:

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

In a custom layout, put these elements inside the player’s <media-container>. With installed skin source, edit its existing gesture declarations. A packaged skin already declares its own gestures, so do not add duplicates.

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

Most names match. Start with these name changes:

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 Chrome’s named icon slots do not carry over. Remove attributes such as slot="play" and put the icon directly inside the Video.js button. With a bundler, import @videojs/html/icons/element to use <media-icon>; the CDN video preset already registers it. See the example in Map the controller. Set family="neutral" or family="compat" to use the Neutral or Compat skin’s icon designs. You can also use your own text or SVG.

media-poster also works differently. Where media-poster-image took its own src, media-poster wraps the image you bring:

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

Ready-made HTML skins keep their controls inside Shadow DOM. Code outside the skin sees a click as coming from the skin, not the button inside it. Some control events also stay inside the skin. Do not use an outside listener to identify which built-in button was clicked.

Keep playback event handlers on your <video> or <audio>. When you build a custom control bar, attach click and input handlers directly to those controls. With a ready-made skin, read media or player state instead of listening for clicks inside the skin.

Keep the skin when its CSS variables and content slots cover your changes. Build a custom control bar when you want to start from scratch. Add the skin source to your project when you want its existing layout and styles but need to change the controls inside it.

Call actions on the player element’s store only after player.store.target is set, which means the media has attached. Fullscreen requests must run from a user interaction:

<button id="toggle-fullscreen" type="button">Toggle fullscreen</button>

<script type="module">
  await customElements.whenDefined('video-player');
  const player = document.querySelector('video-player');

  document.querySelector('#toggle-fullscreen').addEventListener('click', () => {
    if (!player.store.target) return;

    if (player.store.isFullscreen) {
      player.store.exitFullscreen();
    } else {
      player.store.requestFullscreen();
    }
  });
</script>

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

Set visibility="always" on media-controls to keep the controls visible regardless of activity. Packaged skins do not expose this attribute. To keep a packaged skin’s look, add its source to your project and set visibility="always" on its controls element.