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 usageSection titled 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.
Key FeaturesSection titled Key Features
- 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
<audio>elements and many other media elements
InstallSection titled Install
Option 1: HostedSection titled 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@1/+esm"></script>
Modules are always loaded asynchronously by the browser, so it’s ok to load them in the head 👍
Option 2: Bundled via npmSection titled 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.
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 HTMLSection titled Using in your HTML
<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 other none at all. You can find out which slots are available on each components documentation page.
Adding controlsSection titled 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
You could also set the
Compatible media elementsSection titled 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 (
<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 furtherSection titled Taking it further
If you’d like to dive deeper into customization you can check out these resources.