Aurora Player Attributes and Properties

Quick reference

Customizable attributes and properties

HTML attribute	JavaScript property	Description
`media-id`	`mediaId`	Required. The unique ID of a media.
`aspect`	`aspect`	Sets the aspect ratio of the player.
`audio-description-control`	`audioDescriptionControl`	Enabled/disables the Audio Description control in the play bar
`autoplay`	`autoplay`	If set to `true` the media will play as soon as it's ready.
`big-play-button`	`bigPlayButton`	Enables/disables the big play button which appears in the center of the video before play.
`controls-visible-on-load`	`controlsVisibleOnLoad`	Enables/disables whether the control bar is present on load before play.
`copy-link-and-thumbnail`	`copyLinkAndThumbnail`	Enables/disables whether the "Copy link and thumbnail" option is present in context menu.
`current-time`	`currentTime`	Sets the current time of the media as a decimal in seconds.
`do-not-track`	`doNotTrack`	Disables viewing session tracking for heatmaps and other analytics.
`email`	`email`	Sets which specific email address should be associated with this media's viewing sessions.
`end-video-behavior`	`endVideoBehavior`	Sets the behavior of the media when it ends.
`fullscreen-control`	`fullscreenControl`	Enables/disables the fullscreen control in the control bar.
`muted`	`muted`	Mutes/unmutes the media.
`playback-rate-control`	`playbackRateControl`	Enables/disables the playback rate option inside the settings control.
`playback-rate`	`playback-rate`	Set/Get the current playback rate of the media
`play-bar-control`	`playBarControl`	Enables/disables the play bar in the control bar.
`player-color`	`playerColor`	Sets the base color of the player.
`playlist-links`	`playlistLinks`	Associates specially crafted media links on your page with a media, turning all of them together into a playlist.
`playlist-loop`	`playlistLoop`	Enables/disables the behavior of the playlist to loop back to the first media in the list after all media have been played.
`play-pause-control`	`playPauseControl`	Enables/disables the play/pause control in the control bar.
`play-pause-notifier`	`playPauseNotifier`	Enables/disables the brief animation of a pause/play symbol when playing/pausing.
`poster`	`poster`	Sets the thumbnail of the media.
`preload`	`preload`	Sets the loading strategy for the media.
`quality-control`	`qualityControl`	Enables/disables the manual quality selection option in the settings control.
`quality-max`	`qualityMax`	Set the maximum quality for automatic playback.
`quality-min`	`qualityMin`	Set the minimum quality for automatic playback.
`resumable`	`resumable`	Tells the media to pick up where the viewer left off the next time they load the page where the media is embedded.
`rounded-player`	`roundedPlayer`	Controls all rounded corners of the player.
`seo`	`seo`	Enables/disable if the media's metadata will be injected into the page's on-page markup.
`settings-control`	`settingsControl`	Enables/disables the settings control in the control bar.
`silent-autoplay`	`silentAutoplay`	Sets how sound and autoplay work together.
`swatch`	`swatch`	Enables/disables the placeholder image which displays while the player is loading.
`transparent-letterbox`	`transparentLetterbox`	If set to `true` the background behind the player will be transparent, allowing the page color to show through instead of the default black letterboxing.
`video-quality`	`videoQuality`	Sets the quality level of the media.
`volume`	`volume`	Sets the volume of the player.
`volume-control`	`volumeControl`	Enables/disables the volume control in the control bar.

Read-only properties

JavaScript property	Description
`buffered`	Returns a `TimeRanges` object that represents the ranges of the media resource that the user agent has buffered.
`duration`	Returns the duration of the media in seconds.
`embedOptions`	Returns all the embed options being set on the player from attributes and media data.
`ended`	Returns `true` if the media has ended playback.
`eventKey`	Returns the `event_key` for the current viewing session. You can get all events for your account from the Stats API.
`inFullscreen`	Returns `true` if the media is currently in fullscreen.
`name`	Returns the name of the media, as defined in the Wistia application.
`paused`	Returns `true` if the media is paused.
`percentWatched`	Returns the percent of the media that has been watched as a decimal between `0` and `1`.
`readyState`	Returns a value that expresses the current state of the element with respect to rendering the current playback position.
`secondsWatched`	Returns the number of unique seconds that have been watched for the media.
`secondsWatchedVector`	Returns an array where each index represents the number of times the viewer has watched each second of the media.
`state`	Returns the current state of the media.
`visitorKey`	Returns the unique visitor key of the viewer of the media.

Try it!

Attributes:

player-color (🔗):

rounded-player (🔗):

big-play-button (🔗):

fullscreen-control (🔗):

Properties:

currentTime (🔗):

state (🔗): beforeplay

Using attributes and properties

HTML attributes

Attributes are additional values which can be added to <wistia-player> to further customize its look and behavior. Multiple attributes can be set on a <wistia-player> element at once.

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

<!-- This player is red. -->
<wistia-player id="my-player-1" media-id="abc123" player-color="#ff0000"></wistia-player>

<!-- This player is green. -->
<wistia-player id="my-player-2" media-id="abc123" player-color="#00ff00"></wistia-player>

<!-- And this player has a bunch of different options set at once! -->
<wistia-player id="my-player-3" media-id="abc123" big-play-button="false" muted player-color="#0000ff"></wistia-player>

Attributes can also be set on the React component version of the player, <WistiaPlayer>. They're set as props on the component and use camelCase syntax rather than snake-case syntax.

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

// This player is red.
<WistiaPlayer id="my-player-1" mediaId="abc123" playerColor="#ff0000" />

// This player is green.
<WistiaPlayer id="my-player-2" mediaId="abc123" playerColor="#00ff00" />
    
// And this player has a bunch of different options set at once!
<WistiaPlayer id="my-player-3" mediaId="abc123" bigPlayButton={false} muted={true} playerColor="#0000ff" />

JavaScript properties

Every HTML attribute available on <wistia-player> also has a corresponding JavaScript property—so the attribute player-color corresponds to and will be equal to the property playerColor.

Like attributes, properties can be used to set the look and behavior of the <wistia-player>. Properties are set via JavaScript rather than HTML, and they can also be used to get more information than just attributes can provide, such as a player's currentTime, state, and videoQuality.

Properties are usually better than attributes when you need to make an update to <wistia-player> after the initial render of the element because they won't trigger a DOM change.

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

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

<script>
  // This player will now be red.
  const player1 = document.getElementById("my-player-1");
  player1.playerColor = "#ff0000";

  // This player will now be green.
  const player2 = document.getElementById("my-player-2");
  player2.playerColor = "#00ff00";

  // And this player will now not have a big play button, will be muted, and will be blue!
  const player3 = document.getElementById("my-player-3");
  player3.bigPlayButton = false;
  player3.muted = true;
  player3.playerColor = "#0000ff";
</script>

Attributes and properties specific to popover embeds can be found in our Popover Embed Documentation.

`media-id`

Required. The unique ID of a media.

To get the media ID for a video, refer to the URL of the media's page in Wistia. The alphanumeric characters following /medias/ are what you want.

HTML attribute	JavaScript property	Type	Default value	Example values
`media-id`	`mediaId`	`string`	`undefined`	`"abc123"`, `"ns6e2w2xw1"`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" />

`aspect`

Sets the aspect ratio of the player.

HTML attribute	JavaScript property	Type	Default value	Example values
`aspect`	`aspect`	`number`	`undefined`	`1.778`, `16 / 9`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" aspect="1.778"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" aspect={1.778} />

<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"); // Finds the existing player
  player.aspect = 1.778;
  player.aspect; // Returns 1.778
</script>

`audio-description-control`

Enables/disables the Audio Description Control in the control bar.

🙌
Note: If this control is enabled, but no Alternate Audio tracks are found for the video, the control will not appear in the control bar.

HTML attribute	JavaScript property	Type	Default value	Example values
`audio-description-control`	`audioDescriptionControl`	`boolean`	`false`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" audio-description-control="true"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" audioDescriptionControl={true} />

<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"); // Finds the existing player
  player.audioDescriptionControl = true;
  player.audioDescriptionControl; // Returns true
</script>

`autoplay`

If set to true the video will play as soon as it's ready.

You can also add ?wvideo=mediaid to the end of any URL where a Wistia video is embedded, so that it will automatically start playing when your viewer visits that link. You can test this out in your Wistia account too!

🙌
Note: autoplay will not work on iOS and other mobile devices due to restrictions on bandwidth on cellular networks. You can find more information on these restrictions in the Player API Documentation.
Videos will autoplay whenever possible, but some browsers (like most mobile browsers and Safari) prevent video autoplay.

HTML attribute	JavaScript Property	Type	Default value	Example values
`autoplay`	`autoplay`	`boolean`	`false`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" autoplay></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" autoplay={true} />

`big-play-button`

Enables/disables the big play button which appears in the center of the video before play.

HTML attribute	JavaScript property	Type	Default value	Example values
`big-play-button`	`bigPlayButton`	`boolean`	`true`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" big-play-button="false"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" bigPlayButton={false} />

<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"); // Finds the existing player
  player.bigPlayButton = false;
  player.bigPlayButton; // Returns `false`
</script>

`controls-visible-on-load`

Enables/disables whether the control bar is present on load before play.

HTML attribute	JavaScript property	Type	Default value	Example values
`controls-visible-on-load`	`controlsVisibleOnLoad`	`boolean`	`true`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" controls-visible-on-load="false"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" controlsVisibleOnLoad={false} />

`copy-link-and-thumbnail`

Enables/disables whether the "Copy link and thumbnail" option is present in context menu.

If set to false, once your media is embedded on a webpage, the option to "Copy Link and Thumbnail" when you right click on your media will be removed.

🙌
Note: If set to false, you will not be able to create a thumbnail that links to the page where the video is embedded.

HTML attribute	JavaScript property	Type	Default value	Example values
`copy-link-and-thumbnail`	`copyLinkAndThumbnail`	`boolean`	`true`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" copy-link-and-thumbnail="false"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" copyLinkAndThumbnail={false} />

<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"); // Finds the existing player
  player.copyLinkAndThumbnail = false;
  player.copyLinkAndThumbnail; // Returns `false`
</script>

`current-time`

Sets the current time of the media as a decimal in seconds.

This option will maintain the state of the video: if the video was playing, it will continue playing after seek. If it was not playing, the video will be paused.

🙌
Note: On iOS, when seeking from the "beforeplay" state, setting player.currentTime is subject to the same restrictions as player.play(). However, there is a bit of nuance. If you set player.currentTime = 30 before play, the media will not play per the restrictions. But once the viewer clicks the media to play it, it will begin playing 30 seconds in.

HTML attribute	JavaScript property	Type	Default value	Example values
`current-time`	`currentTime`	`number`	`0`	`5`, `10.375`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" current-time="5"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" currentTime={5} />

<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"); // Finds the existing player
  player.currentTime = 3.5;
  player.currentTime; // Returns `3.5`
</script>

`do-not-track`

If set to true, disables viewing session tracking for heatmaps and other analytics.

By default, data for each viewing session is tracked and reported back to the Wistia servers for display in heatmaps and aggregation graphs.

HTML attribute	JavaScript property	Type	Default value	Example values
`do-not-track`	`doNotTrack`	`boolean`	`false`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" do-not-track></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" doNotTrack={true} />

`email`

Sets which specific email address should be associated with this media's viewing sessions.

HTML attribute	JavaScript property	Type	Default value	Example values
`email`	`email`	`string`	`undefined`	`"[email protected]"`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" email="[email protected]"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" email="[email protected]" />

<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"); // Finds the existing player
  player.email = '[email protected]';
  player.email; // Returns `[email protected]`
</script>

`end-video-behavior`

Sets the behavior of the media when it ends.

HTML attribute	JavaScript property	Type	Default value	Example values
`end-video-behavior`	`endVideoBehavior`	`string`	`"default"`	`"default"`, `"loop"`, `"reset"`

Possible values:

Value	Description
`"default"`	Default behavior. The video stays on the last frame
`"reset"`	The video shows the thumbnail. Control Bar visibility depends on controls-visible-on-load
`"loop"`	The video plays again from the beginning

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" end-video-behavior="reset"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" endVideoBehavior="reset" />

<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"); // Finds the existing player
  player.endVideoBehavior = 'reset';
  player.endVideoBehavior; // Returns `'reset'`
</script>

`fullscreen-control`

Enables/disables the fullscreen control in the control bar.

🙌
Note: iframe embeds must have the allowfullscreen attribute for this option to be meaningful. If allowfullscreen attribute is missing, the fullscreen control will not appear.

HTML attribute	JavaScript property	Type	Default value	Example values
`fullscreen-control`	`fullscreenControl`	`boolean`	`true`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" fullscreen-control="false"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" fullscreenControl={false} />

<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"); // Finds the existing player
  player.fullscreenControl = false;
  player.fullscreenControl; // Returns `false`
</script>

`muted`

Enables/disables the audio mute setting of the player.

Set this option to true on the initial load of the player if you would like your video to play silently and not show the "Click For Sound" icon.

HTML attribute	JavaScript property	Type	Default value	Example values
`muted`	`muted`	`boolean`	`false`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" muted></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" muted={true} />

<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"); // Finds the existing player
  player.muted = true;
  player.muted; // Returns `true`
</script>

`playback-rate`

Set the playback rate of the media

HTML attribute	JavaScript property	Type	Default value	Example values
`playback-rate`	`playbackRate`	`string\	number`	`1`	`1.5`, `2`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" playback-rate="2"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" playbackRate={2} />

<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"); // Finds the existing player
  player.playbackRate = 2;
  player.playbackRate; // Returns `2`
</script>

`playback-rate-control`

Enables/disables the playback rate option inside the settings control.

HTML attribute	JavaScript property	Type	Default value	Example values
`playback-rate-control`	`playbackRateControl`	`boolean`	`true`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" playback-rate-control="false"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" playbackRateControl={false} />

<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"); // Finds the existing player
  player.playbackRateControl = false;
  player.playbackRateControl; // Returns `false`
</script>

`play-bar-control`

Enables/disables the play bar in the control bar. The play bar includes the playhead, current time, and scrubbing functionality.

HTML attribute	JavaScript property	Type	Default value	Example values
`play-bar-control`	`playBarControl`	`boolean`	`true`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" play-bar-control="false"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" playBarControl={false} />

<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"); // Finds the existing player
  player.playBarControl = false;
  player.playBarcontrol; // Returns `false`
</script>

`player-color`

Sets the base color of the player. Expects a six-character hexadecimal RGB string like #2949E5. The string can include or exclude the preceding # character.

HTML attribute	JavaScript property	Type	Default value	Example values
`player-color`	`playerColor`	`string`	`"636155"`	`"ff0000"`, `"#00FF00"`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" player-color="#2949E5"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" playerColor="#2949E5" />

<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"); // Finds the existing player
  player.playerColor = "1e64f0";
  player.playerColor; // Returns "1e64f0"
</script>

`playlist-links`

Associates specially crafted media links on your page with a media, turning all of them together into a playlist. For more detailed information about playlist links and their possible values, check out the full Embed Links documentation.

HTML attribute	JavaScript property	Type	Default value	Example values
`playlist-links`	`playlistLinks`	`string`	`undefined`	`"auto"`, `"manual"`, `${containerId}`

Possible values:

Value	Description
`"auto"`	For each video on the page, look for links after the video, until we come to another Wistia video.
`"manual"`	Given each link element, look at its 'container' option to determine which video it should connect to
`${containerId}`	For all embed links in this container, connect them to this specific video.

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" playlist-links="auto"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" playlistLinks="auto" />

<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"); // Finds the existing player
  player.playlistLinks = "auto";
  player.playlistLinks; // Returns "auto"
</script>

`playlist-loop`

If the media has a playlist and this value is set to true, the playlist will loop back to the first media and replay it once the last media has finished.

HTML attribute	JavaScript property	Type	Default value	Example values
`playlist-loop`	`playlistLoop`	`boolean`	`false`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" playlist-loop></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" playlistLoop={true} />

<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"); // Finds the existing player
  player.playlistLoop = true;
  player.playlistLoop; // Returns `true`
</script>

`play-pause-control`

Enables/disables the play/pause control in the control bar.

HTML attribute	JavaScript property	Type	Default value	Example values
`play-pause-control`	`playPauseControl`	`boolean`	`true`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" play-pause-control="false"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" playPauseControl={false} />

<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"); // Finds the existing player
  player.playPauseControl = false;
  player.playPauseControl; // Returns `false`
</script>

`play-pause-notifier`

Enables/disables the brief animation of a pause/play symbol when playing/pausing.

HTML attribute	JavaScript property	Type	Default value	Example values
`play-pause-notifier`	`playPauseNotifier`	`boolean`	`true`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" play-pause-notifier="false"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" playPauseNotifier={false} />

<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"); // Finds the existing player
  player.playPauseNotifier = false;
  player.playPauseNotifier; // Returns `false`
</script>

`poster`

Overrides the thumbnail image which appears before the video plays. Expects an absolute URL to an image. For the best results, the image should match the exact aspect ratio of the video.

HTML attribute	JavaScript property	Type	Default value	Example values
`poster`	`poster`	`string`	`"https://embed-ssl.wistia.com/deliveries/${uuid}/.jpg"`	`"https://my-image.com/picture.jpg"`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" poster="https://my-image.com/picture.jpg"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" poster="https://my-image.com/picture.jpg" />

<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"); // Finds the existing player
  player.poster = "https://my-image.com/picture.jpg"; 
  player.poster; // Returns "https://my-image.com/picture.jpg"
</script>

`preload`

Sets the loading strategy for the media.

🙌
Note: The attribute/property preload must be set before the player is embedded. Changing it after the player is loaded on the page will have no impact.

🙌
Note: Players set to autoplay will have their preload value set to auto by default.

HTML attribute	JavaScript property	Type	Default value	Example values
`preload`	`preload`	`string`	`"metadata"`	`"auto"`, `"none"`, `"metadata"`

Possible values:

Value	Description
`"auto"`	Video/audio metadata is preloaded along with a portion of the media.
`"none"`	No data, other than the bare minimum to render a media player on the page, is preloaded.
`"metadata"`	Only video/audio metadata is preloaded.

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" preload="none"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" preload="none" />

`quality-control`

Enables/disables the manual quality selection option in the settings control.

HTML attribute	JavaScript property	Type	Default value	Example values
`quality-control`	`qualityControl`	`boolean`	`true`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" quality-control="false"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" qualityControl={false} />

<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"); // Finds the existing player
  player.qualityControl = false;
  player.qualityControl; // Returns `false`
</script>

`quality-max`

Set the maximum quality for automatic playback. <wistia-player> will still run bandwidth checks to test for speed and play the highest quality version at or below the set maximum.

🙌
Note: Keep in mind, viewers will still be able to manually select a quality outside the set maximum (using the option on the player) unless quality-control is set to false.

HTML attribute	JavaScript property	Type	Default value	Example values
`quality-max`	`qualityMax`	`number`	`undefined`	`224`, `360`, `540`

Possible values

Value	Description
`224`	224p max
`360`	360p max
`540`	540p max
`720`	720p max
`1080`	1080p max
`3840`	3830p max

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" quality-max="1080"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" qualityMax={1080} />

<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"); // Finds the existing player
  player.qualityMax = 1080; 
  player.qualityMax; // Returns `1080`
</script>

`quality-min`

Set the minimum quality for automatic playback. <wistia-player> will still run bandwidth checks to test for speed and play the highest quality version at or above the set minimum.

🙌
Note: Keep in mind, viewers will still be able to manually select a quality outside the set minimum (using the option on the player) unless quality-control is set to false.

HTML attribute	JavaScript property	Type	Default value	Example values
`quality-min`	`qualityMin`	`number`	`undefined`	`224`, `360`, `540`

Possible values:

Value	Description
`224`	224p min
`360`	360p min
`540`	540p min
`720`	720p min
`1080`	1080p min
`3840`	3830p min

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" quality-min="540"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" qualityMin={540} />

<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"); // Finds the existing player
  player.qualityMin = 540; 
  player.qualityMin; // Returns `540` 
</script>

`resumable`

Tells the media to pick up where the viewer left off the next time they load the page where the media is embedded.

HTML attribute	JavaScript property	Type	Default value	Example values
`resumable`	`resumable`	`boolean` \|\| `"auto"`	`"auto"`	`"auto'`, `true`, `false`

Possible values:

Value	Description
`"auto"`	The resumable feature will only be enabled if the video is 5 minutes or longer, is not autoplay, and is not set to loop at the end.
`true`	Always enables the resumable feature.
`false`	Always disables the resumable feature.

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" resumable></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" resumable={true} />

<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"); // Finds the existing player
  player.resumable = true;
  player.resumable; // Returns `true`
</script>

`rounded-player`

Controls all rounded corners of the player. Expects a number value between 0 and 24.

HTML attribute	JavaScript property	Type	Default value	Example values
`rounded-player`	`roundedPlayer`	`number`	`0`	`5`, `24`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" rounded-player="24"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" roundedPlayer={24} />

<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"); // Finds the existing player
  player.roundedPlayer = 24;
  player.roundedPlayer; // Returns `24`
</script>

`seo`

Enables/disables if the media's metadata will be injected into the page's on-page markup. Learn more about SEO.

🙌
Note: It is best to have this value set correctly immediately upon embed. Otherwise, web crawlers like Google may miss your video's SEO.

🙌
Note: Changing this value from true to false after the video has been embedded will not remove any SEO markup that has already been added to the page.

HTML attribute	JavaScript property	Type	Default value	Example values
`seo`	`seo`	`boolean`	`true`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" seo="false"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" seo={false} />

`settings-control`

Enables/disables the settings control in the control bar. This control allows viewers to control the quality and playback speed of the video.

See quality-control and playback-rate-control if you want more control over what is available within the settings control.

HTML attribute	JavaScript property	Type	Default value	Example values
`settings-control`	`settingsControl`	`boolean`	`true`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" settings-control="false"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" settingsControl={false} />

<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"); // Finds the existing player
  player.settingsControl = false;
  player.settingsControl; // Returns `false`
</script>

`silent-autoplay`

Sets how sound and autoplay work together. This option allows videos to autoplay in a muted state in contexts where normal autoplay is blocked or not supported (e.g. iOS, Safari 11+, Chrome 66+).

The silent-autoplay option will act as an autoplay preference, but will not have the video autoplay by itself. In order for this option to work, the video will need to be set to play through the autoplay embed option or set via Customize within the Wistia app.

🙌
Note: A video is considered to be "autoplaying" if the play() command is not issued within a user-generated event (like a click) or within the "end" event handler (e.g. for the next video in a playlist).

If you need to see when the video enters and exits "silent playback mode," refer to the docs on the silent-playback-mode-change event.

HTML attribute	JavaScript property	Type	Default value	Example values
`silent-autoplay`	`silentAutoplay`	`boolean` \|\| `"allow"`	`false`	`true`, `false`, `"allow"`

Possible values:

Value	Description
`"allow"`	The video will default to normal autoplay, with silent autoplay as a fallback if needed
`true`	The video will default to autoplaying silently
`false`	The video will not autoplay silently

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" autoplay silent-autoplay="allow"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" autoplay={true} silentAutoplay="allow" />

`swatch`

Enables/disables the placeholder image which displays while the player is loading. Changing this option after the player has loaded will have no effect.

HTML attribute	JavaScript property	Type	Default value	Example values
`swatch`	`swatch`	`boolean`	`true`	`true`, `false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" swatch="false"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" swatch={false} />

`transparent-letterbox`

If set to true the background behind the player will be transparent, allowing the page color to show through instead of the default black letterboxing. Letterboxing may occur if there's an aspect ratio discrepancy between the dimensions of the video and its container—this option is not connected to alpha transparency.

HTML attribute	JavaScript property	Type	Default value	Example values
`transparent-letterbox`	`transparentLetterbox`	`boolean`	`false`	`true`,`false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" transparent-letterbox="false"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" transparentLetterbox={false} />

<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"); // Finds the existing player
  player.transparentLetterbox = false;
  player.transparentLetterbox; // Returns `false`
</script>

`video-quality`

Sets and returns the quality level of the media. It accepts either an integer indicating the exact quality level to stream (ex. 224, 360, etc) or the string "auto" to enable adaptive bit rate streaming.

🙌
Note: If you specify a quality level corresponding to an asset that doesn't exist for your media, videoQuality will default to the highest or lowest quality asset available. For example, if you pass 1080 as an argument but your video doesn't have a 1080p asset, videoQuality will select the 720p asset instead.

HTML attribute	JavaScript property	Type	Default value	Example values
`video-quality`	`videoQuality`	`number` \| `"auto"`	`"auto"`	`720`, `"auto"`

Possible values:

Value	Description
`"auto"`	Enable adaptive bit rate streaming.
`224`	224p
`360`	360p
`540`	540p
`720`	720p
`1080`	1080p
`3840`	3830p

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" video-quality="360"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" videoQuality={360} />

<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"); // Finds the existing player
  player.videoQuality = 720;
  player.videoQuality; // Returns `720`
</script>

`volume`

Set the volume of the media. Expects an integer value between 0 and 1. To mute the media on load, set this option to 0.

HTML attribute	JavaScript property	Type	Default value	Example values
`volume`	`volume`	`number`	`1`	`0`,`0.5`, `1`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" volume="0.5"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" volume={0.5} />

<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"); // Finds the existing player
  player.volume = 0.5;
  player.volume; // Returns `0.5`
</script>

`volume-control`

Enables/disables the volume control in the control bar.

🙌
Note: On mobile devices where we use the native volume controls, this option has no effect.

HTML attribute	JavaScript property	Type	Default value	Example values
`volume-control`	`volumeControl`	`boolean`	`true`	`true`,`false`

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" volume-control="false"></wistia-player>

import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" volumeControl={false} />

<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"); // Finds the existing player
  player.volumeControl = false;
  player.volumeControl; // Returns `false`
</script>

Using read-only properties

Read-only JavaScript properties cannot be set, and provide useful information about the data and state of the <wistia-player>. Properties like duration and state can be used alongside other player attributes, properties, events, and methods to build out functionality for the <wistia-player>.

<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>
<button type="button" id="halfway-button">Skip to the halfway point!</button>

<script>
  const player = document.getElementById('my-player');
  const halfwayButton = document.getElementById('halfway-button');

  // When a button is clicked...
  halfwayButton.addEventListener('click', () => {
    // Use the read-only duration property to set the media to its halfway point
    player.currentTime = player.duration / 2;
  });
</script>

`buffered`

Read only. Returns a TimeRanges object that represents the ranges of the media resource that the user agent has buffered.

JavaScript property	Type	Example values
`buffered`	`object`	`{ end: end(index), length: 1, start: start(index) }`

Example code:

<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'); // Finds the existing player
  console.log(player.buffered);
  
  // Example output: TimeRanges{ end: end(index), length: 1, start: start(index) }
</script>

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

export default function App() {
  const player = useRef(null);
  
  function handleApiReady() {
    if (player.current === null) { return; }
    console.log(player.current.buffered);
    
    // Example output: TimeRanges{ end: end(index), length: 1, start: start(index) }
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onApiReady={handleApiReady} />
  );
}

`duration`

Read only. Returns the duration of the media as a decimal in seconds. This will return 0 until the on-api-ready event has fired.

JavaScript property	Type	Example values
`duration`	`number`	`5.125`, `120`, `0`

Example code:

<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'); // Finds the existing player
  console.log(`This video is ${player.duration} seconds long.`);
  
  // Example output: "This video is 120 seconds long."
</script>

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

export default function App() {
  const player = useRef(null);
  
  function handleApiReady() {
    if (player.current === null) { return; }
    console.log(`This video is ${player.current.duration} seconds long.`);
    
    // Example output: "This video is 120 seconds long."
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onApiReady={handleApiReady} />
  );
}

`embedOptions`

Read only. Returns all the embed options being set on the player from attributes and media data.

JavaScript property	Type	Example values
`embedOptions`	`object`	`{}`, `{ playerColor: "00ff00", fullscreenControl: false }`

Example code:

<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'); // Finds the existing player
  console.log(player.embedOptions);
  
  // Example output: { playerColor: "00ff00", fullscreenControl: false }
</script>

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

export default function App() {
  const player = useRef(null);
  
  function handleApiReady() {
    if (player.current === null) { return; }
    console.log(player.current.embedOptions);
    
    // Example output: { playerColor: "00ff00", fullscreenControl: false }
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onApiReady={handleApiReady} />
  );
}

`ended`

Read only. Returns true if the media has ended playback.

JavaScript property	Type	Example values
`ended`	`boolean`	`true`, `false`

Example code:

<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'); // Finds the existing player
  console.log(`The media has${player.ended ? "" : " not"} ended.`);
  
  // Example output: "The media has ended."
</script>

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

export default function App() {
  const player = useRef(null);
  
  function handleEnded() {
    if (player.current === null) { return; }
    console.log(`The media has${player.current.ended ? "" : " not"} ended.`);
    
    // Example output: "The media has ended."
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onEnded={handleEnded} />
  );
}

`eventKey`

Read only. Returns the event_key for the current viewing session, if it exists. You can get all events for your account from the Stats API.

JavaScript property	Type	Example values
`eventKey`	`string` \| `undefined`	`undefined`, `"123-abc-4567-89"`

Example code:

<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'); // Finds the existing player
  console.log(player.eventKey);
  
  // Example output: "123-abc-4567-89"
</script>

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

export default function App() {
  const player = useRef(null);
  
  function handleApiReady() {
    if (player.current === null) { return; }
    console.log(player.current.eventKey);
    
    // Example output: "123-abc-4567-89"
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onApiReady={handleApiReady} />
  );
}

`inFullscreen`

Read only. Returns true if the media is currently in fullscreen.

JavaScript property	Type	Example values
`inFullscreen`	`boolean`	`true`, `false`

Example code:

<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'); // Finds the existing player
  console.log(`The player is${player.inFullscreen ? "" : " not"} currently in fullscreen.`);
  
  // Example output: "The player is not currently in fullscreen."
</script>

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

export default function App() {
  const player = useRef(null);
  
  function handleCancelFullscreen() {
    if (player.current === null) { return; }
    console.log(`The player is${player.current.inFullscreen ? "" : " not"} currently in fullscreen.`);
    
    // Example output: "The player is not currently in fullscreen."
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onCancelFullscreen={handleCancelFullscreen} />
  );
}

`name`

Read only. Returns the name of the media, as defined in the Wistia application. Returns undefined until the loaded-media-data event has fired.

JavaScript property	Type	Example values
`name`	`string` \| `undefined`	`"My Video Title"`, `"Lenny Delivers Video"`, `undefined`

Example code:

<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'); // Finds the existing player
  console.log(player.name);
  
  // Example output: "Lenny Delivers Video"
</script>

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

export default function App() {
  const player = useRef(null);
  
  function handleLoadedMediaData() {
    if (player.current === null) { return; }
    console.log(player.current.name);
    
    // Example output: "Lenny Delivers Video"
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onLoadedMediaData={handleLoadedMediaData} />
  );
}

`paused`

Read only. Returns true if the media is paused.

JavaScript property	Type	Example values
`paused`	`boolean`	`true`, `false`

Example code:

<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'); // Finds the existing player
  console.log(`The player is${player.paused ? "" : " not"} paused.`);
  
  // Example output: "The player is paused."
</script>

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

export default function App() {
  const player = useRef(null);
  
  function handlePause() {
    if (player.current === null) { return; }
    console.log(`The player is${player.current.paused ? "" : " not"} paused.`);
    
    // Example output: "The player is paused."
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onPause={handlePause} />
  );
}

`percentWatched`

Read only. Returns the percent of the media that has been watched as a decimal between 0 and 1. This is equivalent to computing player.secondsWatched / Math.floor(player.duration).

This percentage value is relative to where a viewer started playback during their viewing session. For example, if a viewer starts the video in the middle and watches it to the end, player.percentWatched will return 0.5. If that same viewer in that same session then starts the video from the beginning and watches to the middle, player.percentWatched will return 1, as the whole video has now been watched.

JavaScript property	Type	Example values
`percentWatched`	`number`	`0`, `0.7525`

Example code:

<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'); // Finds the existing player
  console.log(`The viewer has watched ${(player.percentWatched * 100)}% of the video.`);
  
  // Example output: "The viewer has watched 75.25% of the video."
</script>

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

export default function App() {
  const player = useRef(null);
  
  function handlePercentWatchedChange() {
    if (player.current === null) { return; }
    console.log(`The viewer has watched ${(player.current.percentWatched * 100)}% of the video.`);
    
    // Example output: "The viewer has watched 75.25% of the video."
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onPercentWatchedChange={handlePercentWatchedChange} />
  );
}

`readyState`

Read only. Returns a value that expresses the current state of the element with respect to rendering the current playback position.

JavaScript property	Type	Example values
`readyState`	`number`	`0`, `4`

Possible values:

Value	Corresponding state	Description
`0`	`HAVE_NOTHING`	No information regarding the media resource is available.
`1`	`HAVE_METADATA`	Enough of the resource has been obtained that the duration of the resource is available.
`2`	`HAVE_CURRENT_DATA`	Data for the immediate current playback position is available.
`3`	`HAVE_FUTURE_DATA`	Data for the immediate current playback position is available and there is enough data for future playback without having to immediately revert to `HAVE_METADATA`.
`4`	`HAVE_ENOUGH_DATA`	All previous conditions are met and data is loading at a pace which will not be overtaken by the default playback rate.

Example code:

<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'); // Finds the existing player
  console.log(player.readyState)
  
  // Example output: 4
</script>

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

export default function App() {
  const player = useRef(null);
  
  function handleApiReady() {
    if (player.current === null) { return; }
    console.log(player.current.readyState)
    
    // Example output: 4
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onApiReady={handleApiReady} />
  );
}

`secondsWatched`

Read only. Returns the number of unique seconds that have been watched for the media. This does not include seconds that have been skipped by seeking.

JavaScript property	Type	Example values
`secondsWatched`	`number`	`0`, `24`

Example code:

<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'); // Finds the existing player
  console.log(`The viewer has watched ${player.secondsWatched} seconds.`);
  
  // Example output: "The viewer has watched 24 seconds."
</script>

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

export default function App() {
  const player = useRef(null);
  
  function handleSecondChange() {
    if (player.current === null) { return; }
    console.log(`The viewer has watched ${player.current.secondsWatched} seconds.`);
    
    // Example output: "The viewer has watched 24 seconds."
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onSecondChange={handleSecondChange} />
  );
}

`secondsWatchedVector`

Read only. Returns an array where each index represents the number of times the viewer has watched each second of the media. This can be used to quickly determine if a viewer has missed or rewatched an important part of a video.

For example, if a media is 10 seconds long and the viewer has watched the first three seconds, it will look like this:

[1, 1, 1, 0, 0, 0, 0, 0, 0, 0]

If the viewer has watched the entire video once and rewatched the first 5 seconds, it will look like this:

[2, 2, 2, 2, 2, 1, 1, 1, 1, 1]

JavaScript property	Type	Example values
`secondsWatchedVector`	`object`	`[1, 1, 0, 0, 0]`, `[1, 2, 1, 2, 2, 1, 1, 1]`

Example code:

<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'); // Finds the existing player
  player.addEventListener("ended", () => {
    var watchedVector = player.secondsWatchedVector;
    var watchedImportantSeconds = 0;
    for (var i = 4; i < 9; i++) {
      if (watchedVector[i] > 0) {
        watchedImportantSeconds += 1;
      }
     }
    if (watchedImportantSeconds < 2) {
      console.log("You should really go back and watch seconds 5 through 10. They're important!");
    }
  });
</script>

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

export default function App() {
  const player = useRef(null);
  
  function handleEnded() {
    if (player.current === null) { return; }
    var watchedVector = player.current.secondsWatchedVector;
    var watchedImportantSeconds = 0;
    for (var i = 4; i < 9; i++) {
      if (watchedVector[i] > 0) {
        watchedImportantSeconds += 1;
      }
    }
    if (watchedImportantSeconds < 2) {
      console.log("You should really go back and watch seconds 5 through 10. They're important!");
    }
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onEnded={handleEnded} />
  );
}

`state`

Read only. Returns the current state of the media. The most common use case for state is implementing a play/pause toggle button.

JavaScript property	Type	Example values
`state`	`string`	`true`, `false`

Possible values:

Value	Description
`"beforeplay"`	Initial state of the media.
`"playing"`	The media is currently playing.
`"paused"`	The media was playing, but is now paused.
`"ended"`	The media has ended playback.

Example code:

<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123"></wistia-player>
<button type="button" id="play-pause-button">Play / Pause</button>

<script>
  const player = document.getElementById('my-player'); // Finds the existing player
  const customPlayPauseButton = document.getElementById('play-pause-button');

  customPlayPauseButton.addEventListener('click', () => {
    if (player.state === 'playing') { // Read player state
      player.pause();
    } else {
      player.play();
    }
  });
</script>

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

export default function App() {
  const player = useRef(null);
  
  function handleClick() {
    if (player.current === null) { return; }
    
    if (player.current.state === 'playing') { // Read player state
      player.current.pause();
    } else {
      player.current.play();
    }
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" />
    <button type="button" onClick={handleClick}>Play / Pause</button>
  );
}

`visitorKey`

Read only. Returns the unique visitor key of the person watching the video. This is used to associate multiple viewing sessions with a single person. You can use it to filter events in the Stats API.

JavaScript property	Type	Example values
`visitorKey`	`string`	`"123_abc"`, `undefined`

Example code:

<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'); // Finds the existing player
  console.log(`This viewer's visitor key is ${player.visitorKey}.`);
  
  // Example output: "This viewer's visitor key is 123_abc."
</script>

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

export default function App() {
  const player = useRef(null);
  
  function handlePlay() {
    if (player.current === null) { return; }
    console.log(`This viewer's visitor key is ${player.current.visitorKey}.`);
    
    // Example output: "This viewer's visitor key is 123_abc."
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onPlay={handlePlay} />
  );
}