Get Started

Media Chrome is a collection of fully customizable media player controls and components. You can use these components to build a media player from scratch.

A key focus of Media Chrome is to separate the UI from media playback. This means that the underlying playback engine can be swapped out while leaving the UI intact.

Example usage

This example demonstrates combining controls, captions, poster image, and a timeline with thumbnails on hover. This is a live sandbox so you can edit the code and see it update in real-time. Try adding <media-volume-range></media-volume-range> to the control bar.

<media-controller>
  <video
    slot="media"
    src="https://stream.mux.com/A3VXy02VoUinw01pwyomEO3bHnG4P32xzV7u1j1FSzjNg/high.mp4"
    poster="https://image.mux.com/A3VXy02VoUinw01pwyomEO3bHnG4P32xzV7u1j1FSzjNg/thumbnail.jpg"
  ></video>
  <media-control-bar>
    <media-play-button></media-play-button>
    <media-mute-button></media-mute-button>
    <media-time-range></media-time-range>
    <media-time-display></media-time-display>
    <media-fullscreen-button></media-fullscreen-button>
  </media-control-bar>
</media-controller>

Open Sandbox

Key Features

Web Components: Use with or without a JavaScript framework, compatible with: React, Angular, VueJS, Svelte, and more.
Styling: Use simple CSS to style components
Theming: Build custom themes that group together controls and style
Accessible: All controls express their state in an accessible way
Unified API: Compatible with standard <video> and <audio> elements and many other media elements

Install

Media Chrome is packaged as an ES6 JavaScript module which is supported by all evergreen browsers and Node v12+.

Option 1: Hosted

Load the module in the <head> of your HTML page. Note the type="module", that’s important.

<script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/+esm"></script>

Modules are always loaded asynchronously by the browser, so it’s ok to load them in the head 👍

Option 2: Bundled via npm

Install via npm (you could also use Yarn or your favorite package manager)

npm install media-chrome --save

Import into your app.

import 'media-chrome';

Importing the package like this will automatically register all of the core Media Chrome components in the browser. This means you can add a control like <media-play-button> to your page.

Using in your HTML

The <media-controller> component handles all of the communication between controls and the media being presented. To use it, wrap your media element with a <media-controller>, and add slot="media" to it.

<media-controller>
  <video
    slot="media"
    src="https://stream.mux.com/DS00Spx1CV902MCtPj5WknGlR102V5HFkDe/high.mp4"
  ></video>
</media-controller>

We’re using a standard HTML <video> element here, but you could use any other compatible media element.

Slots are a feature of Web Components that allow you choose where an element should be placed. In this instance, we’re telling media controller to place our video tag where media elements should go. Some Media Chrome components will define multiple slots and others none at all. You can find out which slots are available on each components documentation page.

Adding controls

You can add controls to your player by placing them inside of a <media-control-bar>. By default, this control bar will appear at the bottom of the player.

<media-controller>
  <video
    slot="media"
    src="https://stream.mux.com/DS00Spx1CV902MCtPj5WknGlR102V5HFkDe/high.mp4"
  ></video>
  <media-control-bar>
    <media-play-button></media-play-button>
    <media-mute-button></media-mute-button>
    <media-volume-range></media-volume-range>
    <media-time-range></media-time-range>
    <media-pip-button></media-pip-button>
    <media-fullscreen-button></media-fullscreen-button>
  </media-control-bar>
</media-controller>

Unlike the video element we didn’t specify a “slot”. This means that the control bar will be placed into the default slot, which is reserved for controls.

When using controls outside of a <media-controller> wrapper element; the control, or the surrounding control bar, needs to specify which media controller it should be associated with. To do this you can set the mediacontroller attribute.

<media-controller id="myController">
  <video slot="media" src="https://stream.mux.com/A3VXy02VoUinw01pwyomEO3bHnG4P32xzV7u1j1FSzjNg/high.mp4" muted playsinline></video>
</media-controller>

<media-control-bar mediacontroller="myController">
  <media-play-button></media-play-button>
  <media-time-range></media-time-range>
</media-control-bar>

Open Sandbox

You could also set the mediaController property of the element with JavaScript

Compatible media elements

Media elements are in charge of controlling the playback of media and present no UI on their own. The <media-controller> component mediates events between the controls and the media element for you.

Media Chrome will work with any element that exposes the same API as the HTML media elements (<video> and <audio>). This means that you can replace these elements with your own if they conform to the same API. You can read more about the HTMLMediaElement API on MDN.

There are many compatible media elements available that you can replace the standard <video> element with. Check out the media elements section in the left sidebar menu.

Taking it further

If you’d like to dive deeper into customization you can check out these resources.