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.

Size and position the player in CSS layouts

The <wistia-player> web component sizes itself from the width of its container, then derives its height from the video's aspect ratio. Internally the component sets :host { display: flex; position: relative; width: 100%; }, so by default it fills the available width and computes height as width ÷ aspect (16:9 unless the media or the aspect attribute says otherwise). Once you know sizing flows width → height, most layout problems solve themselves.

Responsive width (the default, and what you usually want)

Drop the player into a normal block container and it fills the width, keeping the video's aspect ratio:

<div style="max-width: 640px;">
  <wistia-player media-id="abc123"></wistia-player>
</div>

The player is as wide as .wrapper allows and as tall as 16:9 requires. No height needs to be set anywhere.

Force a specific aspect ratio

To render at an aspect ratio other than the video's native one (for example a 1:1 square), set the aspect attribute rather than fighting the height with CSS:

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

Fixed-height and overflow-hidden containers

A fixed-height, overflow: hidden wrapper (common for hero banners and Next.js layouts) is the usual source of a collapse-to-zero-height player. The player derives its height from width, so pinning the wrapper's height and expecting the player to fill it fights that model. Give the player a wrapper it can fill and let it stretch to that box:

<div style="position: relative; width: 100%; height: 400px; overflow: hidden;">
  <wistia-player
    media-id="abc123"
    style="position: absolute; inset: 0; width: 100%; height: 100%;"
  ></wistia-player>
</div>

Setting height: 100% on the player element itself (not only on the wrapper) is what lets it fill a fixed-height box. Because the player uses object-fit-style contain internally, the video is letterboxed inside the box rather than distorted.

Framework-rendered layouts (Next.js, etc.)

The same rules apply inside React/Next.js — size the wrapper, not the shadow DOM. If you're seeing layout shift as the player upgrades, reserve space up front with the React component's aspect prop:

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

See Prevent layout shift (React) above for the full CLS pattern.