Aurora React Component

Installation

The @wistia/wistia-player-react package contains a <WistiaPlayer> React component, which makes it easy to embed, customize, and interact with a Wistia Player within your React application.

To install it, run this command in your project folder:

npm install @wistia/wistia-player-react

Basic usage

Once the package is installed, you can use the component in your application to embed a player:

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

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

Attributes

The only required prop on <WistiaPlayer> is mediaId.

The <WistiaPlayer> component can take all the same attributes which can be set on the <wistia-player> web component as props instead, with some slight formatting differences:

  1. Attribute props are camelCase instead of kebab-case.
  2. When setting the value of an attribute prop, the value type should match what the prop is expecting. If a prop expects a number, then its value should be set as a number rather than a string.

So if you have a <wistia-player> web component embed which looks like this:

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

<wistia-player media-id="abc123" autoplay player-color="#0000ff" volume="0.5"></wistia-player>

Its React equivalent would look like this:

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

<WistiaPlayer mediaId="abc123" autoplay={true} playerColor="#0000ff" volume={0.5} />

A full list of attributes and properties, as well as their React equivalents, can be found in our Attributes and Properties Documentation.

Events

Events can also be added to the <WistiaPlayer> React component. All our documented events are supported, with some slight formatting differences:

  1. Events props are camelCase instead of kebab-case.
  2. Event prop names are preceded by the word on.

So if you have an event callback on a <wistia-player> web component embed which looks like this:

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

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

<script>
  const player = document.getElementById("my-player");
  player.addEventListener("play", () => {
    console.log("The video was just played!");
  });
</script>

Its React equivalent would look like this:

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

export default function App() {
  function handlePlay() {
    console.log("The video was just played!");
  };
  
  return (
    <WistiaPlayer mediaId="abc123" onPlay={handlePlay} />
  );
}

A full list of events, as well as examples of their usage in React, can be found in our Events Documentation.

Methods

All our documented methods are supported on the <WistiaPlayer> React component. To call methods, you'll need a reference to the player you want to interact with:

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

export default function App() {
  const myPlayer = useRef(null);
  
  // When our custom button is clicked, play the video.
  function handleClick() {
    if (myPlayer.current === null) { return; }
    myPlayer.current.play();
  }
  
  return (
    <WistiaPlayer ref={myPlayer} mediaId="abc123" />
    <button type="button" onClick={handleClick}>Play</button>
  );
}

A full list of methods, as well as examples of their usage in React, can be found in our Methods Documentation.


Solving layout shift

In order to make your player look like it's loading super fast, the <WistiaPlayer> React component will automatically load a swatchβ€”which is a small, compressed placeholder thumbnailβ€”as soon as that swatch image can be loaded.

However, loading an image on a page still takes time, no matter how small that image is. In the time that it takes to load a swatch, visitors to your site may see a slight shift in layout of your page.

Before

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

<WistiaPlayer mediaId="abc123" />

In order to avoid any potential layout shift from the player embed, you can pass the aspect ratio of your video into the aspect prop on the <WistiaPlayer> component. That value lets us know exactly how much space the player should take up on the page so we can reserve can that space in your layout.

And voilaβ€”no more layout shift!

After

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

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

Fixed-size embeds

The <WistiaPlayer> component is responsive by default. If a fixed-size player is better for your use-case, you can pass in width and height values instead:

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

<WistiaPlayer
  mediaId="abc123"
  style={{
    width: "640px",	
    height: "360px",
  }}
/>

Popovers

A "Popover" is a player embed type which displays a player in a modal which pops out over the page when a target element is clicked. To change your <WistiaPlayer> React component into a popover-style embed, the wistiaPopover prop is required to be set to true:

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

<WistiaPlayer mediaId="abc123" wistiaPopover={true} />

For more information about popovers, as well as examples of their attributes, properties, events, and methods in React, can be found in our Popover Embed API Documentation.