Embedding the Aurora Player: Quick Start Guide

Wistia's latest version of our player embed is a custom HTML web component (<wistia-player) which can be dropped right into your page or included with your site's build pipeline. We also have a React component wrapper of <wistia-player> for convenience.

Hosted HTML

When getting an embed code through Wistia's in-app interface, you'll usually receive a chunk of code which looks something like the following:

<script src="https://fast.wistia.com/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

<style>
  wistia-player[media-id='abc123']:not(:defined) {
    background: center / contain no-repeat
      url('https://fast.wistia.com/embed/medias/abc123/swatch');
    display: block;
    filter: blur(5px);
    padding-top: 56.25%;
  }
</style>

<wistia-player media-id="abc123"></wistia-player>

This code can be dropped directly into your site's HTML to render a Wistia player.

If you're looking for ways to programmatically customize and manipulate your embed code, we've got you covered in our Embed API Documentation.

If you want your embed to be a popover, you can check out our Popover Embed API Documentation.

npm

We've also created an npm package @wistia/wistia-player which can be included in your app's build pipeline.

To use it, first run this command in your project folder:

npm install @wistia/wistia-player

Now that the player package has been added to your app, you can import it and use it wherever you want to render a player in HTML:

import '@wistia/wistia-player';

// However you render in your JS app:
<wistia-player media-id="abc123"></wistia-player>

Or, you can create a <wistia-player> element using only JavaScript:

import '@wistia/wistia-player';

const player = document.createElement('wistia-player');
player.mediaId = 'abc123';

document.body.append(player);

React

If your project uses React, we've created a wrapper component for <wistia-player> which lives in the @wistia/wistia-player-react npm package.

To use it, first run this command in your project folder:

npm install @wistia/wistia-player-react

And now that the player package has been added to your app, you can import the WistiaPlayer wrapper component and use it wherever you want to render a player:

import { WistiaPlayer } from "@wistia/wistia-player-react"; 

export default function App() {
  return (
    <WistiaPlayer mediaId="abc123" />
  );
}

For more information on the React component and how you can use it to avoid content shift on your page, check out our React Component Documentation.

Performance & lazy loading

Wistia's embed is built to stay light until a viewer actually engages. Before you reach for a custom lazy-loading attribute, it helps to know what the player already does and which knobs are yours to turn.

What the embed does by default

• preload="metadata" is the default. The player fetches only enough metadata to render controls and the placeholder — it does not download video segments until playback starts. You do not need to add anything to get this behavior.
• The swatch is your placeholder. The <style> block in the standard embed code paints a small, blurred swatch image (a highly compressed thumbnail) while the player initializes, so viewers see the video frame immediately with almost no weight on the page.

Defer media data with preload="none"

If you have several players on one page, or a player below the fold, set preload="none" so the player downloads nothing beyond the bare minimum to render until the viewer clicks play:

<wistia-player media-id="abc123" preload="none"></wistia-player>

Prevent layout shift (React)

To reserve space for the player and avoid Cumulative Layout Shift (CLS), pass your video's aspect ratio to the aspect prop on the React component:

<WistiaPlayer mediaId="abc123" aspect={16 / 9} />

See Solving layout shift for the full pattern.

What isn't configurable

Some PageSpeed and Lighthouse suggestions map to HTML attributes that Wistia's embed does not expose — adding them to the generated markup has no effect:

• loading="lazy" on the embed — the <wistia-player> web component is not an <iframe> or <img>, so the native loading attribute does not apply. Use preload="none" for the deferred-load behavior instead.
• fetchpriority on the swatch/thumbnail — the placeholder image is generated by the embed; you can't set fetchpriority on it. If a swatch is being flagged as a high-priority request, preload="none" reduces the player's overall load footprint.

Many players on one page

If a page renders a large number of players, the most effective optimization is to not embed them all at once. Render a lightweight placeholder (a linked thumbnail or a poster image) and swap in the <wistia-player> on click or when it scrolls into view, so only the players a visitor actually engages with ever download the player script and media data.