<mux-uploader> is a drop-in web component that makes it easy to upload video files to Mux.

This component allows you to build a fully-functional video upload UI in your application using a single line of code.

// First, install it
npm i @mux/mux-uploader

// Then, import it
import '@mux/mux-uploader';

// Finally, add the html tag
<div>
  <mux-uploader></mux-uploader>
</div>

If you're using npm or yarn, install that way:

yarn add @mux/mux-uploader

or

npm i @mux/mux-uploader

Then, import the library into your application with either import or require:

import '@mux/mux-uploader';

or

require('@mux/mux-uploader');

Alternatively, use the CDN hosted version of this package:

<script src="https://cdn.jsdelivr.net/npm/@mux/mux-uploader@1.0.0-beta.6"></script>

If you are using ECMAScript modules, you can also load the mux-uploader.mjs file with type=module:

<script type="module" src="https://cdn.jsdelivr.net/npm/@mux/mux-uploader@1.0.0-beta.6/dist/mux-uploader.mjs"></script>

mux-uploader takes care of rendering a file selector, uploading your video file, displaying progress updates to the user, handling retries, and more.

There's only one required attribute that you must set to upload your file – the endpoint attribute. It looks like this:

<mux-uploader endpoint="https://my-authenticated-url/storage?your-url-params"></mux-uploader>

The endpoint attribute provides mux-uploader with a direct upload URL that will receive the video file you're uploading.

You can generate a signed direct upload URL by making a server-side API call to Mux's Create Direct Upload endpoint.

In a successful API response, you will receive a unique signed upload URL that can then be passed along to your client application and set as the endpoint property on a mux-uploader element. The URL for a Direct Upload looks like "https://storage.googleapis.com/video...".

In the following examples, you will replace the value of the endpoint property with your unique direct upload URL.

At the time you render the <mux-uploader>, you may not have the direct upload URL yet. Instead, you might want to retrieve it async from your server after a user selects a file. You can do that by setting the endpoint property value to a custom function instead of a URL.

<mux-uploader></mux-uploader>

<script>
  const muxUploader = document.querySelector('mux-uploader');
  /*
    Endpoint should be a function that returns a promise and resolves
    with a string for the upload URL.
  */
  muxUploader.endpoint = function () {
    /*
      In this example, your server endpoint would return the upload URL
      in the response body "https://storage.googleapis.com/video..."
    */
    return fetch('/your-server/api/create-upload').then(res => res.text());
  };
</script>

We've built <mux-uploader> with sensible styling defaults that might Just Work™ for your application.

Of course, there are times when you'll want to change the default appearance or behavior to something a little more custom.

<mux-uploader> uses HTML slots, allowing you to replace default UI elements with your own HTML elements.

View the slots reference to learn about all of the available slots in <mux-uploader>.

Example: using your own file selector

You can use your own button with the slot="file-select" attribute.

This is really handy if, for example, you already have a .btn class that styles buttons in your application.

<style>
  .btn {
    /* your styles for .btn */
    padding: 6px 8px;
    border: 1px solid #0d9488;
    border-radius: 5px;
    font-size: 24px;
    color: #134e4a;
    background: #99f6e4;
    cursor: pointer;
  }
</style>

<!-- slot="file-select" tells mux-uploader to replace the default file selector with a button.btn element -->
<mux-uploader endpoint="https://my-authenticated-url/storage?your-url-params">
  <button class="btn" type="button" slot="file-select">Pick a file</button>
</mux-uploader>

<mux-uploader> exposes CSS variables that allow you to change the default styling of the uploader UI.

View the CSS variables reference to learn about all of the available CSS variables in <mux-uploader>.

Example: Customizing the progress bar

By default, the progress bar color is black with a gray background. Here's how you can change the progress bar color to purple:

<style>
  mux-uploader {
    --progress-bar-fill-color: #7e22ce;
  }
</style>

<mux-uploader endpoint="https://my-authenticated-url/storage?your-url-params">
  <button class="btn" type="button" slot="file-select">Pick a file</button>
</mux-uploader>

If you're looking to build a custom UI for uploading videos in your application, advanced customization is for you.

You can use the individual web components that come packaged with <mux-uploader> to build out a custom upload UI that meets your needs.

To use this approach, add an id attribute to your <mux-uploader> element with a unique value.

You can then associate the <mux-uploader> element with any of the packaged components by adding a mux-uploader="" attribute to each component.

Example:

<!-- add a mux-uploader tag with an id attribute and hide it with CSS -->
<mux-uploader id="my-uploader" style="display: none;"></mux-uploader>

<!-- ...then, somewhere else in your app, add a reference back to it -->
<mux-uploader-file-select mux-uploader="my-uploader">
  <button slot="file-select">Pick a video</button>
</mux-uploader-file-select>

Here are all of the available components you can use with <mux-uploader>:

Check out the mux-uploader-modal.html example application to see a real-world example of how these components can be used.

<mux-uploader-drop> is available for drag and drop functionality. It works like a <div> or other "container" element in the sense that you can style it and populate it with whatever children you see fit (including but not necessarily a <mux-uploader>).

Similar to <input> and <label> relationships, you associate a <mux-uploader-drop> with its corresponding <mux-uploader> via id using the mux-uploader attribute.

The <mux-uploader-drop> component will get the active attribute when the drag is active, this allows you to write some CSS to style it for your application.

Here's a full example of a custom button, customized progress text and drag and drop functionality that changes the background when the drag is active

<style>
  /* This .btn class styles buttons in my application */
  .btn {
    padding: 6px 8px;
    border: 1px solid #0d9488;
    border-radius: 5px;
    font-size: 24px;
    color: #134e4a;
    background: #99f6e4;
    cursor: pointer;
  }
  /* Customize progress bar color */
  mux-uploader {
    --progress-bar-fill-color: #7e22ce;
  }
  /* Customize drop area background color & active background color */
  mux-uploader-drop {
    display: block;
    padding: 40px;
    background: #fef9c3;
  }
  mux-uploader-drop[active] {
    background: #ffe4e6;
  }
</style>

<mux-uploader-drop mux-uploader="my-uploader">
  <mux-uploader id="my-uploader" endpoint="https://my-authenticated-url/storage?your-url-params">
    <button class="btn" type="button" slot="file-select">Pick a file</button>
  </mux-uploader>
</mux-uploader-drop>

Technical details about drop areas:

When a file is dropped, <mux-uploader> will dispatch a custom file-ready event with the relevant file.

You can implement your own drag and drop completely separate from <mux-uploader> and as long as you dispatch a custom file-ready with the file in the detail property then <mux-uploader> will handle the upload upon receiving the event.

<script>
  const muxUploader = document.querySelector('mux-uploader');

  // Dispatch custom event to trigger upload
  muxUploader.dispatchEvent(
    new CustomEvent('file-ready', {
      composed: true,
      bubbles: true,
      detail: file,
    })
  );
</script>

<mux-uploader> uses custom events to share details about how the upload is progressing.

You can listen for the progress event to receive details on how far along your file upload is.

  const muxUploader = document.querySelector('mux-uploader');

  muxUploader.addEventListener('progress', function (e) {
    console.log(`My upload is ${e.detail}% complete!`)
  });

When the upload is complete, you'll see 100% on the progress bar and the success event will fire.

If an error occurs during the upload, an uploaderror event will fire.

<mux-uploader endpoint="https://my-authenticated-url/storage?your-url-params"></mux-uploader>

<script>
  const muxUploader = document.querySelector('mux-uploader');
  muxUploader.addEventListener('success', function () {
    /* Handle upload success */
  });

    muxUploader.addEventListener('uploaderror', function () {
    /* Handle upload error */
  });
<script>

<mux-uploader> fires several events throughout the uploading lifecycle to monitor uploading state. These events match the events fired by Upchunk under the hood.

<mux-uploader> and its packaged components can be styled with standard CSS, but also includes the following CSS variables for "under the hood" styling.