Aurora Attributes and Properties
Learn more about the attributes and properties available for your embedded player.
Quick reference
Attributes and properties
Attribute | Description |
---|---|
media-id | Required. The unique ID of a media. |
aspect | Sets the aspect ratio of the player. |
audio-description-control | Enabled/disables the Audio Description control in the play bar |
autoplay | If set to true the media will play as soon as it's ready. |
big-play-button | Enables/disables the big play button which appears in the center of the video before play. |
controls-visible-on-load | Enables/disables whether the control bar is present on load before play. |
copy-link-and-thumbnail | Enables/disables whether the "Copy link and thumbnail" option is present in context menu. |
current-time | Sets the current time of the media as a decimal in seconds. |
do-not-track | Disables viewing session tracking for heatmaps and other analytics. |
email | Sets which specific email address should be associated with this media's viewing sessions. |
end-video-behavior | Sets the behavior of the media when it ends. |
fullscreen-control | Enables/disables the fullscreen control in the control bar. |
muted | Mutes/unmutes the media. |
playback-rate-control | Enables/disables the playback rate option inside the settings control. |
play-bar-control | Enables/disables the play bar in the control bar. |
player-color | Sets the base color of the player. |
playlist-links | Associates specially crafted media links on your page with a media, turning all of them together into a playlist. |
playlist-loop | 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 | Enables/disables the play/pause control in the control bar. |
play-pause-notifier | Enables/disables the brief animation of a pause/play symbol when playing/pausing. |
poster | Sets the thumbnail of the media. |
preload | Sets the loading strategy for the media. |
quality-control | Enables/disables the manual quality selection option in the settings control. |
quality-max | Set the maximum quality for automatic playback. |
quality-min | Set the minimum quality for automatic playback. |
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 | Controls all rounded corners of the player. |
seo | Enables/disable if the media's metadata will be injected into the page's on-page markup. |
settings-control | Enables/disables the settings control in the control bar. |
silent-autoplay | Sets how sound and autoplay work together. |
swatch | Enables/disables the placeholder image which displays while the player is loading. |
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. |
video-quality | Sets the quality level of the media. |
volume | Sets the volume of the player. |
volume-control | Enables/disables the volume control in the control bar. |
Read-only properties
Name | 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:
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
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.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
media-id | mediaId | string | undefined | "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
aspect
Sets the aspect ratio of the player.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
aspect | aspect | number | undefined | 1.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
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.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
audio-description-control | audioDescriptionControl | boolean | false | true , 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
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.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
autoplay | autoplay | boolean | false | true , 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
big-play-button
Enables/disables the big play button which appears in the center of the video before play.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
big-play-button | bigPlayButton | boolean | true | true , 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
controls-visible-on-load
Enables/disables whether the control bar is present on load before play.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
controls-visible-on-load | controlsVisibleOnLoad | boolean | true | true , 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
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.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
copy-link-and-thumbnail | copyLinkAndThumbnail | boolean | true | true , 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
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, settingplayer.currentTime
is subject to the same restrictions asplayer.play()
. However, there is a bit of nuance. If you setplayer.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.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
current-time | currentTime | number | 0 | 5 , 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
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.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
do-not-track | doNotTrack | boolean | false | true , 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
email
Sets which specific email address should be associated with this media's viewing sessions.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
email | email | string | undefined | "[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
end-video-behavior
Sets the behavior of the media when it ends.
Attribute | 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:
<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
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. Ifallowfullscreen
attribute is missing, the fullscreen control will not appear.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
fullscreen-control | fullscreenControl | boolean | true | true , 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
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.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
muted | muted | boolean | false | true , 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
playback-rate-control
Enables/disables the playback rate option inside the settings control.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
playback-rate-control | playbackRateControl | boolean | true | true , 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
play-bar-control
Enables/disables the play bar in the control bar. The play bar includes the playhead, current time, and scrubbing functionality.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
play-bar-control | playBarControl | boolean | true | true , 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
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.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
player-color | playerColor | string | "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
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.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
playlist-links | playlistLinks | string | undefined | "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
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.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
playlist-loop | playlistLoop | boolean | false | true , 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
play-pause-control
Enables/disables the play/pause control in the control bar.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
play-pause-control | playPauseControl | boolean | true | true , 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
play-pause-notifier
Enables/disables the brief animation of a pause/play symbol when playing/pausing.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
play-pause-notifier | playPauseNotifier | boolean | true | true , 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
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.
Attribute | 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:
<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
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.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
preload | preload | string | "auto" | "auto" , "none" , "metadata" |
Possible values:
Value | Description |
---|---|
"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
quality-control
Enables/disables the manual quality selection option in the settings control.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
quality-control | qualityControl | boolean | true | true , 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
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 tofalse
.
Attribute | 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:
<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
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 tofalse
.
Attribute | 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:
<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
resumable
Tells the media to pick up where the viewer left off the next time they load the page where the media is embedded.
Attribute | 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:
<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
rounded-player
Controls all rounded corners of the player. Expects a number value between 0
and 24
.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
rounded-player | roundedPlayer | number | 0 | 5 , 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
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
tofalse
after the video has been embedded will not remove any SEO markup that has already been added to the page.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
seo | seo | boolean | true | true , 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
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.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
settings-control | settingsControl | boolean | true | true , 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
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.
Attribute | 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:
<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
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.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
swatch | swatch | boolean | true | true , 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
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.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
transparent-letterbox | transparentLetterbox | boolean | false | true ,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
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 pass1080
as an argument but your video doesn't have a 1080p asset,videoQuality
will select the 720p asset instead.
Attribute | 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 |
<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
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
.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
volume | volume | number | 1 | 0 ,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
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.
Attribute | Property | Type | Default value | Example values |
---|---|---|---|---|
volume-control | volumeControl | boolean | true | true ,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
buffered
Read only. Returns a TimeRanges
object that represents the ranges of the media resource that the user agent has buffered.
Property | Type | Example values |
---|---|---|
buffered | object | { 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
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.
Property | Type | Example values |
---|---|---|
duration | number | undefined | 5.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
embedOptions
Read only. Returns all the embed options being set on the player from attributes and media data.
Property | Type | Example values |
---|---|---|
embedOptions | object | {} , { 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
ended
Read only. Returns true
if the media has ended playback.
Property | Type | Example values |
---|---|---|
ended | boolean | true , 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
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.
Property | Type | Example values |
---|---|---|
eventKey | string | undefined | undefined , "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
inFullscreen
Read only. Returns true
if the media is currently in fullscreen.
Property | Type | Example values |
---|---|---|
inFullscreen | boolean | true , 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
name
Read only. Returns the name of the media, as defined in the Wistia application. Returns undefined
until the loadedmetadata
event has fired.
Property | Type | Example values |
---|---|---|
name | string | 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
paused
Read only. Returns true
if the media is paused.
Property | Type | Example values |
---|---|---|
paused | boolean | true , 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
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.
Property | Type | Example values |
---|---|---|
percentWatched | number | 0 , 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
readyState
Read only. Returns a value that expresses the current state of the element with respect to rendering the current playback position.
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. |
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
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.
Property | Type | Example values |
---|---|---|
secondsWatched | number | 0 , 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
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]
Property | Type | Example values |
---|---|---|
secondsWatchedVector | object | [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
state
Read only. Returns the current state of the media. The most common use case for state
is implementing a play/pause toggle button.
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. |
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
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.
Property | Type | Example values |
---|---|---|
visitorKey | string | "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} />
);
}
Updated 17 days ago