Aurora Attributes and Properties

Learn more about the attributes and properties available for your embedded player.

Quick reference

Attributes and properties

AttributeDescription
media-idRequired. The unique ID of a media.
aspectSets the aspect ratio of the player.
audio-description-controlEnabled/disables the Audio Description control in the play bar
autoplayIf set to true the media will play as soon as it's ready.
big-play-buttonEnables/disables the big play button which appears in the center of the video before play.
controls-visible-on-loadEnables/disables whether the control bar is present on load before play.
copy-link-and-thumbnailEnables/disables whether the "Copy link and thumbnail" option is present in context menu.
current-timeSets the current time of the media as a decimal in seconds.
do-not-trackDisables viewing session tracking for heatmaps and other analytics.
emailSets which specific email address should be associated with this media's viewing sessions.
end-video-behaviorSets the behavior of the media when it ends.
fullscreen-controlEnables/disables the fullscreen control in the control bar.
mutedMutes/unmutes the media.
playback-rate-controlEnables/disables the playback rate option inside the settings control.
play-bar-controlEnables/disables the play bar in the control bar.
player-colorSets the base color of the player.
playlist-linksAssociates specially crafted media links on your page with a media, turning all of them together into a playlist.
playlist-loopEnables/disables the behavior of the playlist to loop back to the first media in the list after all media have been played.
play-pause-controlEnables/disables the play/pause control in the control bar.
play-pause-notifierEnables/disables the brief animation of a pause/play symbol when playing/pausing.
posterSets the thumbnail of the media.
preloadSets the loading strategy for the media.
quality-controlEnables/disables the manual quality selection option in the settings control.
quality-maxSet the maximum quality for automatic playback.
quality-minSet the minimum quality for automatic playback.
resumableTells the media to pick up where the viewer left off the next time they load the page where the media is embedded.
rounded-playerControls all rounded corners of the player.
seoEnables/disable if the media's metadata will be injected into the page's on-page markup.
settings-controlEnables/disables the settings control in the control bar.
silent-autoplaySets how sound and autoplay work together.
swatchEnables/disables the placeholder image which displays while the player is loading.
transparent-letterboxIf 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-qualitySets the quality level of the media.
volumeSets the volume of the player.
volume-controlEnables/disables the volume control in the control bar.

Read-only properties

NameDescription
bufferedReturns a TimeRanges object that represents the ranges of the media resource that the user agent has buffered.
durationReturns the duration of the media in seconds.
embedOptionsReturns all the embed options being set on the player from attributes and media data.
endedReturns true if the media has ended playback.
eventKeyReturns the event_key for the current viewing session. You can get all events for your account from the Stats API.
inFullscreenReturns true if the media is currently in fullscreen.
nameReturns the name of the media, as defined in the Wistia application.
pausedReturns true if the media is paused.
percentWatchedReturns the percent of the media that has been watched as a decimal between 0 and 1.
readyStateReturns a value that expresses the current state of the element with respect to rendering the current playback position.
secondsWatchedReturns the number of unique seconds that have been watched for the media.
secondsWatchedVectorReturns an array where each index represents the number of times the viewer has watched each second of the media.
stateReturns the current state of the media.
visitorKeyReturns the unique visitor key of the viewer of the media.

Try it!

Attributes:

Properties:

beforeplay

Using attributes and properties

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/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

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

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

<!-- And this player has a bunch of different options set at once! -->
<wistia-player 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 mediaId="abc123" playerColor="#ff0000" />

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

Properties

Every attribute available on <wistia-player> also has a corresponding property—so the attribute player-color is 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.

// This player is red.
const player1 = document.createElement("wistia-player");
player1.mediaId = "abc123";
player1.playerColor = "#ff0000";
document.body.appendChild(player1);

// This player is green.
const player2 = document.createElement("wistia-player");
player2.mediaId = "abc123";
player2.playerColor = "#00ff00";
document.body.appendChild(player2);

// And this player has a bunch of different options set at once!
const player3 = document.createElement("wistia-player");
player3.mediaId = "abc123";
player3.bigPlayButton = false;
player3.muted = true;
player3.playerColor = "#0000ff";
document.body.appendChild(player3);

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.

AttributePropertyTypeDefault valueExample values
media-idmediaIdstringundefined"abc123", "ns6e2w2xw1"

Example code:

<wistia-player media-id="abc123"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
  
// Set mediaId option
player.mediaId = "abc123";
player.mediaId; // Returns "abc123"

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" />

aspect

Sets the aspect ratio of the player.

AttributePropertyTypeDefault valueExample values
aspectaspectnumberundefined1.7, 0.5625

Example code:

<wistia-player media-id="abc123" aspect="1.7"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set aspect option
player.aspect = 1.7;
player.aspect; // Returns 1.7

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" aspect={1.7} />

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.

AttributePropertyTypeDefault valueExample values
audio-description-controlaudioDescriptionControlbooleanfalsetrue, false

Example Code

<wistia-player media-id="abc123" audio-description-control="true"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set audioDescriptionControl option
player.audioDescriptionControl = true;
player.audioDescriptionControl; // Returns true

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

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

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.

AttributePropertyTypeDefault valueExample values
autoplayautoplaybooleanfalsetrue, false

Example code:

<wistia-player media-id="abc123" autoplay></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set autoplay option
player.autoplay = true;
player.autoplay; // Returns true

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

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

big-play-button

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

AttributePropertyTypeDefault valueExample values
big-play-buttonbigPlayButtonbooleantruetrue, false

Example code:

<wistia-player media-id="abc123" big-play-button="false"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set bigPlayButton option
player.bigPlayButton = false;
player.bigPlayButton; // Returns `false`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" bigPlayButton={false} />

controls-visible-on-load

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

AttributePropertyTypeDefault valueExample values
controls-visible-on-loadcontrolsVisibleOnLoadbooleantruetrue, false

Example code:

<wistia-player media-id="abc123" controls-visible-on-load="false"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set controlsVisibleOnLoad option
player.controlsVisibleOnLoad = false;
player.controlsVisibleOnLoad; // Returns `false`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer 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.

AttributePropertyTypeDefault valueExample values
copy-link-and-thumbnailcopyLinkAndThumbnailbooleantruetrue, false

Example code:

<wistia-player media-id="abc123" copy-link-and-thumbnail="false"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set copyLinkAndThumbnail option
player.copyLinkAndThumbnail = false;
player.copyLinkAndThumbnail; // Returns `false`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" copyLinkAndThumbnail={false} />

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.

AttributePropertyTypeDefault valueExample values
current-timecurrentTimenumber05, 10.375
<wistia-player media-id="abc123" current-time="5"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";

// Set currentTime option
player.currentTime = 3.5;
player.currentTime; // Returns `3.5`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" currentTime={5} />

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.

AttributePropertyTypeDefault valueExample values
do-not-trackdoNotTrackbooleanfalsetrue, false

Example code:

<wistia-player media-id="abc123" do-not-track></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set doNotTrack option
player.doNotTrack = true;
player.doNotTrack; // Returns `true`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

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

email

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

AttributePropertyTypeDefault valueExample values
emailemailstringundefined"[email protected]"

Example code:

<wistia-player media-id="abc123" email="[email protected]"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set email option
player.email = '[email protected]';
player.email; // Returns `[email protected]`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" email="[email protected]" />

end-video-behavior

Sets the behavior of the media when it ends.

AttributePropertyTypeDefault valueExample values
end-video-behaviorendVideoBehaviorstring"default""default", "loop", "reset"

Possible values:

ValueDescription
"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:

<wistia-player media-id="abc123" end-video-behavior="reset"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set endVideoBehavior option
player.endVideoBehavior = 'reset';
player.endVideoBehavior; // Returns `'reset'`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" endVideoBehavior="reset" />

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.

AttributePropertyTypeDefault valueExample values
fullscreen-controlfullscreenControlbooleantruetrue, false

Example code:

<wistia-player media-id="abc123" fullscreen-control="false"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set fullscreenControl option
player.fullscreenControl = false;
player.fullscreenControl; // Returns `false`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" fullscreenControl={false} />

muted

Adding this attribute or setting its value to true will start the video in a muted state.

Use this option if you would like your video to play silently and not show the "Click For Sound" icon.

AttributePropertyTypeDefault valueExample values
mutedmutedbooleanfalsetrue, false

Example code:

<wistia-player media-id="abc123" muted></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set muted option
player.muted = true;
player.muted; // Returns `true`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

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

playback-rate-control

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

AttributePropertyTypeDefault valueExample values
playback-rate-controlplaybackRateControlbooleantruetrue, false

Example code:

<wistia-player media-id="abc123" playback-rate-control="false"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set playbackRateControl option
player.playbackRateControl = false;
player.playbackRateControl; // Returns `false`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" playbackRateControl={false} />

play-bar-control

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

AttributePropertyTypeDefault valueExample values
play-bar-controlplayBarControlbooleantruetrue, false

Example code:

<wistia-player media-id="abc123" play-bar-control="false"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set playBarControl option
player.playBarControl = false;
player.playBarcontrol; // Returns `false`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" playBarControl={false} />

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.

AttributePropertyTypeDefault valueExample values
player-colorplayerColorstring"636155""ff0000", "#00FF00"

Example code:

<wistia-player media-id="abc123" player-color="#2949E5"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set player color option
player.playerColor = "1e64f0";
player.playerColor; // Returns "1e64f0"

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" playerColor="#2949E5" />

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.

AttributePropertyTypeDefault valueExample values
playlist-linksplaylistLinksstringundefined"auto", "manual", ${containerId}

Possible values:

Example code:

<wistia-player media-id="abc123" playlist-links="auto"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set playlistLinks option
player.playlistLinks = "auto";
player.playlistLinks; // Returns "auto"

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" playlistLinks="auto" />

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.

AttributePropertyTypeDefault valueExample values
playlist-loopplaylistLoopbooleanfalsetrue, false

Example code:

<wistia-player media-id="abc123" playlist-links="auto" playlist-loop></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set playlistLinks option
player.playlistLinks = "auto";

// Set playlistLoop option
player.playlistLoop = true; // Returns "true"

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" playlist-links="auto" playlistLoop={true} />

play-pause-control

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

AttributePropertyTypeDefault valueExample values
play-pause-controlplayPauseControlbooleantruetrue, false

Example code:

<wistia-player media-id="abc123" play-pause-control="false"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set playPauseControl option
player.playPauseControl = false; 
player.playPauseControl  // returns `false` 

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" playPauseControl={false} />

play-pause-notifier

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

AttributePropertyTypeDefault valueExample values
play-pause-notifierplayPauseNotifierbooleantruetrue, false

Example code:

<wistia-player media-id="abc123" play-pause-notifier="false"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set playPauseNotifier option
player.playPauseNotifier = false; 
player.playPauseNotifier  // returns `false` 

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" playPauseNotifier={false} />

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.

AttributePropertyTypeDefault valueExample values
posterposterstring"https://embed-ssl.wistia.com/deliveries/${uuid}/.jpg""https://my-image.com/picture.jpg"

Example code:

<wistia-player media-id="abc123" poster="https://my-image.com/picture.jpg"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set poster option
player.poster = 'https://my-image.com/picture.jpg'; 
player.poster  // returns `https://my-image.com/picture.jpg` 

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" poster="https://my-image.com/picture.jpg" />

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.

AttributePropertyTypeDefault valueExample values
preloadpreloadstring"auto""auto", "none", "metadata"

Possible values:

ValueDescription
"auto"All data is preloaded.
"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:

<wistia-player media-id="abc123" preload="none"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set preload option
player.preload = false; 
player.preload  // returns `false` 

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" preload="none" />

quality-control

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

AttributePropertyTypeDefault valueExample values
quality-controlqualityControlbooleantruetrue, false

Example code:

<wistia-player media-id="abc123" quality-control="false"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set qualityControl option
player.qualityControl = false; 
player.qualityControl  // returns `false` 

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" qualityControl={false} />

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.

AttributePropertyTypeDefault valueExample values
quality-maxqualityMaxnumberundefined224, 360, 540

Possible values

ValueDescription
224224p max
360360p max
540540p max
720720p max
10801080p max
38403830p max

Example code:

<wistia-player media-id="abc123" quality-max="1080"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set qualityMax option
player.qualityMax = 1080; 
player.qualityMax  // returns `1080` 

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" qualityMax={1080} />

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.

AttributePropertyTypeDefault valueExample values
quality-minqualityMinnumberundefined224, 360, 540

Possible values:

ValueDescription
224224p min
360360p min
540540p min
720720p min
10801080p min
38403830p min

Example code:

<wistia-player media-id="abc123" quality-min="540"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set qualityMin option
player.qualityMin = 540; 
player.qualityMin  // returns `540` 

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" qualityMin={540} />

resumable

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

AttributePropertyTypeDefault valueExample values
resumableresumableboolean || "auto""auto""auto', true, false

Possible values:

ValueDescription
"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.
trueAlways enables the resumable feature.
falseAlways disables the resumable feature.

Example Code:

<wistia-player media-id="abc123" resumable></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set resumable option
player.resumable = true;
player.resumable; // Returns `true`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

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

rounded-player

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

AttributePropertyTypeDefault valueExample values
rounded-playerroundedPlayernumber05, 24

Example code:

<wistia-player media-id="abc123" rounded-player="24"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set rounded player option
player.roundedPlayer = 24;
player.roundedPlayer; // Returns 24

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" roundedPlayer={24} />

seo

Enables/disable 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.

AttributePropertyTypeDefault valueExample values
seoseobooleantruetrue, false

Example code:

<wistia-player media-id="abc123" seo="false"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set seo option
player.seo = false;
player.seo; // Returns `false`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer 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.

AttributePropertyTypeDefault valueExample values
settings-controlsettingsControlbooleantruetrue, false

Example code:

<wistia-player media-id="abc123" settings-control="false"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set settingsControl option
player.settingsControl = false;
player.settingsControl; // Returns `false`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" settingsControl={false} />

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.

AttributePropertyTypeDefault valueExample values
silent-autoplaysilentAutoplayboolean || "allow"falsetrue, false, "allow"

Possible values:

ValueDescription
"allow"The video will default to normal autoplay, with silent autoplay as a fallback if needed
trueThe video will default to autoplaying silently
falseThe video will not autoplay silently

Example code:

<wistia-player media-id="abc123" autoplay silent-autoplay="allow"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set silentAutoplay option
player.silentAutoplay = 'allow';
player.siltenAutoplay; // Returns `'allow'`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" 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.

AttributePropertyTypeDefault valueExample values
swatchswatchbooleantruetrue, false

Example code:

<wistia-player media-id="abc123" swatch="false"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set settingsControl option
player.swatch = false;
player.swatch; // Returns `false`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer 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.

AttributePropertyTypeDefault valueExample values
transparent-letterboxtransparentLetterboxbooleanfalsetrue,false

Example code:

<wistia-player media-id="abc123" transparent-letterbox="false"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set transparentLetterbox option
player.transparentLetterbox = false;
player.transparentLetterbox; // Returns `false`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" transparentLetterbox={false} />

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.

AttributePropertyTypeDefault valueExample values
video-qualityvideoQualitynumber | "auto""auto"720, "auto"

Possible values:

ValueDescription
"auto"Enable adaptive bit rate streaming.
224224p
360360p
540540p
720720p
10801080p
38403830p
<wistia-player media-id="abc123" video-quality="360"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";

// Set videoQuality option
player.videoQuality = 720;
player.transparentLetterbox; // Returns `720`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" videoQuality={360} />

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.

AttributePropertyTypeDefault valueExample values
volumevolumenumber10,0.5, 1

Example code:

<wistia-player media-id="abc123" volume="0.5"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set volume option
player.volume = 0.5;
player.volume; // Returns `0.5`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" volume={0.5} />

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.

AttributePropertyTypeDefault valueExample values
volume-controlvolumeControlbooleantruetrue,false

Example code:

<wistia-player media-id="abc123" volume-control="false"></wistia-player>
// Set up a new player
const player = document.createElement("wistia-player");
player.mediaId = "abc123";
  
// Set volumeControl option
player.volumeControl = false;
player.volumeControl; // Returns `false`

// Add player to document
document.body.appendChild(player);
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

<WistiaPlayer mediaId="abc123" volumeControl={false} />

Using read-only properties

Read-only 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 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.

PropertyTypeExample values
bufferedobject{ end: end(index), length: 1, start: start(index) }
const player = document.getElementById('my-player');
console.log(player.buffered);

// Example output: TimeRanges{ end: end(index), length: 1, start: start(index) }
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.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 undefined until the loaded-metadata event has fired.

PropertyTypeExample values
durationnumber | undefined5.125, 120, undefined
const player = document.getElementById('my-player');
console.log(`This video is ${player.duration} seconds long.`);

// Example output: "This video is 120 seconds long."
import { useRef } from "react";
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  const player = useRef(null);
  
  function handleLoadedMetadata() {
    if (player.current === null) { return; }
    console.log(`This video is ${player.duration} seconds long.`);

		// Example output: "This video is 120 seconds long."
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onLoadedMetadata={handleLoadedMetadata} />
  );
}

embedOptions

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

PropertyTypeExample values
embedOptionsobject{}, { playerColor: "00ff00", fullscreenControl: false }
const player = document.getElementById('my-player');
console.log(player.embedOptions);

// Example output: { playerColor: "00ff00", fullscreenControl: false }
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.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.

PropertyTypeExample values
endedbooleantrue, false
const player = document.getElementById('my-player');
console.log(`The media has${player.ended ? "" : " not"} ended.`);

// Example output: "The media has ended."
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.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.

PropertyTypeExample values
eventKeystring | undefinedundefined, "123-abc-4567-89"
const player = document.getElementById('my-player');
console.log(player.eventKey);

// Example output: "123-abc-4567-89"
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.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.

PropertyTypeExample values
inFullscreenbooleantrue, false
const player = document.getElementById('my-player');
console.log(`The media is${player.inFullscreen ? "" : " not"} currently in fullscreen.`);

// Example output: "The media is not currently in fullscreen."
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 media is${player.inFullscreen ? "" : " not"} currently in fullscreen.`);

		// Example output: "The media 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 loadedmetadata event has fired.

PropertyTypeExample values
namestring | undefined"My Video Title", "Lenny Delivers Video", undefined
const player = document.getElementById('my-player');
console.log(player.name);

// Example output: "Lenny Delivers Video"
import { useRef } from "react";
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  const player = useRef(null);
  
  function handleLoadedMetadata() {
    if (player.current === null) { return; }
    console.log(player.name);

		// Example output: "Lenny Delivers Video"
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onLoadedMetadata={handleLoadedMetadata} />
  );
}

paused

Read only. Returns true if the media is paused.

PropertyTypeExample values
pausedbooleantrue, false
const player = document.getElementById('my-player');
console.log(`The media is${player.paused ? "" : " not"} paused.`);

// Example output: "The media is paused."
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 media is${player.paused ? "" : " not"} paused.`);

		// Example output: "The media 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.

PropertyTypeExample values
percentWatchednumber0, 0.7525
const player = document.getElementById('my-player');
console.log(`The viewer has watched ${(player.percentWatched * 100)}% of the video.`);

// Example output: "The viewer has watched 75.25% of the video."
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.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.

PropertyTypeExample values
readyStatenumber0, 4

Possible values:

ValueCorresponding stateDescription
0HAVE_NOTHINGNo information regarding the media resource is available.
1HAVE_METADATAEnough of the resource has been obtained that the duration of the resource is available.
2HAVE_CURRENT_DATAData for the immediate current playback position is available.
3HAVE_FUTURE_DATAData for the immediate current playback position is available and there is enough data for future playback without having to immediately revert to HAVE_METADATA.
4HAVE_ENOUGH_DATAAll previous conditions are met and data is loading at a pace which will not be overtaken by the default playback rate.
const player = document.getElementById('my-player');
console.log(player.readyState)

// Example output: 4
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.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.

PropertyTypeExample values
secondsWatchednumber0, 24
const player = document.getElementById('my-player');
console.log(`The viewer has watched ${player.secondsWatched} seconds.`);

// Example output: "The viewer has watched 24 seconds."
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.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]
PropertyTypeExample values
secondsWatchedVectorobject[1, 1, 0, 0, 0], [1, 2, 1, 2, 2, 1, 1, 1]
const player = document.getElementById('my-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!");
  }
});
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; }
    
    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!");
    }
  }
  
  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.

PropertyTypeExample values
statestringtrue, false

Possible values:

ValueDescription
"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.
const player = document.getElementById('my-player');
const customPlayPauseButton = document.getElementById('play-pause-button');

customPlayPauseButton.addEventListener('click', () => {
  if (player.state === 'playing') {
    player.pause();
  } else {
    player.play();
  }
});
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.state === 'playing') {
      player.pause();
    } else {
      player.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.

PropertyTypeExample values
visitorKeystring"123_abc", undefined
const player = document.getElementById('my-player');
console.log(`This viewer's visitor key is ${player.visitorKey}.`);

// Example output: "This viewer's visitor key is 123_abc."
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.visitorKey}.`);

		// Example output: "This viewer's visitor key is 123_abc."
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onPlay={handlePlay} />
  );
}

What’s Next