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:
- Attribute props are
camelCase
instead ofkebab-case
. - 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 anumber
rather than astring
.
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:
- Events props are
camelCase
instead ofkebab-case
. - 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.
Updated 10 days ago