components

Upload component

The upload component allows you to upload directly from your site. The only thing you need is our component library and a generated JWT token.

<script
  type="module"
  src="https://cdn.video-dns.com/npm/@maveio/components/+esm"
></script>

<mave-upload token="<token>"></mave-upload>

The token required is a generated JWT (JSON Web Token) using the API key provided by mave.

Depending on what you set as sub you can determine what to do. You can see this as the scope of the upload:

1. sub: {space id}: adds a new video to the space
2. sub: {collection id}: adds a new video to the collection
3. sub: {embed id}: replaces the video with a the upload

Your space id can be found in settings: developers and the collection id can be found on the page of the collection itself, underneath the title.

Alhough you can generate a “static” JWT, we would recommended creating temporary JWTs with an expiration date. This way you can revoke the JWT at any time and prevent abuse. This is how you can implement this:

While the following example demonstrates the usage in a node.js environment, JWT is widely supported across various languages and frameworks:

// server
const jwt = require("jsonwebtoken");

const token = jwt.sign(
  {
    sub: "XD9HPRtkDDmENLeVy9ripU", // space, collection or embed can be specified
    exp: 1680795697, // until when the user can upload
  },
  "SHJmNHhXNnFublZXajNCNllYUmhoTTpUVDRqZ3ZqYWJtOEtVbmNFb2h2d1RY" // API key
);

// return `token` to frontend

Note: Allowing to upload without an exp means this upload component will always (until you revoke your API key) be valid. We highly recommend using an appropriate exp to prevent abuse.

Once the token is added to <mave-upload token="{token}" /> the upload component will be active and ready to use.

Properties

Events

For example, to catch the upload in Javascript and replace it once the client has completed the upload, you can do the following:

const upload = document.querySelector("mave-upload");
upload.addEventListener("completed", (event) => {
  const player = document.createElement("mave-player");
  player.setAttribute("embed", event.detail.embed);
  upload.parentNode.replaceChild(player, upload);
});

Customising the interface

<mave-upload> still ships with defaults, but you can now provide your own markup for every phase of the upload flow by adding named slots.

<mave-upload token="<token>">
  <div slot="initial" class="initial-card">
    <h2>Upload your media</h2>
    <p>Drop a file or use the button below.</p>
    <button type="button" data-mave-upload-select>Choose a file</button>
  </div>

  <div slot="uploading" class="uploading-card">
    <div class="bar">
      <div class="bar__value" style="width: 0%"></div>
    </div>
    <span data-role="progress-value">0%</span>
  </div>

  <div slot="processing" class="processing-card">Processing…</div>
  <div slot="done" class="done-card">All set!</div>
  <div slot="error" class="error-card">
    <p>Something went wrong. Try again.</p>
    <button type="button" data-mave-upload-select>Try again</button>
  </div>
</mave-upload>

• slot="initial" | "uploading" | "processing" | "done" | "error" decides which layout shows for that state.
• Add data-mave-upload-select to an element inside the initial slot to open the built-in file picker.
• Listen for statechange to react to progress or drag state changes.

const upload = document.querySelector("mave-upload");
const progressValue = upload.querySelector('[data-role="progress-value"]');
const progressBar = upload.querySelector(".bar__value");

upload.addEventListener("statechange", ({ detail }) => {
  const { state, progress, dragging } = detail;
  progressValue.textContent = `${progress}%`;
  progressBar.style.width = `${progress}%`;
  upload.toggleAttribute("drag-highlight", dragging);
});

Every state is also exposed on the host element so you can drive purely-CSS styling:

• Host attributes: state="initial|uploading|processing|done|error", progress="0-100", drag-over, ready.

For example, if you want to highlight mave-upload when someone drags a file over it, you can do something like this:

mave-upload[drag-over] [slot="initial"] {
  box-shadow: inset 0 0 0 2px rgba(99, 102, 241, 0.5);
}

Methods

Complete example of customized upload component

Check out our example page on Github.