iFrame Embed Options

Learn how to use deeply nested options in your iframe embeds.

The Wistia video player has a JavaScript API which supports a number of ways to interact with and control the video player. It uses the same interface for both Flash and HTML5 versions of the player, and provides convenience functions to accomplish common goals.

Before going on, note that we do not advise you to use this syntax. If you find yourself needing to set deeply nested options, it's almost always easier to just switch to a Standard embed or rely on customizing your video directly in Wistia. But if you can't do either of those things, then read on.



The Wistia APIs were specifically built for videos in projects. We do not formally support using our APIs for audio files in projects, or audio or video episodes in Channels at this time. For the most reliable experience, we recommend continuing to use these for videos in projects.

Iframe Embed Options and Bracket Notation

You can modify options for an iframe embed by adding query params to the iframe's src attribute.

Take this iframe embed as an example:

<!-- example_iframe_embed_with_videofoam.html -->
<iframe src="https://fast.wistia.net/embed/iframe/g5pnf59ala?seo=true&videoFoam=false" title="Dan Mills - Young and Free Video" allow="autoplay; fullscreen" allowtransparency="true" frameborder="0" scrolling="no" class="wistia_embed" name="wistia_embed" msallowfullscreen width="640" height="360"></iframe>
<script src="https://fast.wistia.net/assets/external/E-v1.js" async></script>

This iframe has the videoFoam option set to false. You can use the same format for any other option. For example:

<!-- example_iframe_src_with_options.html -->

Adding nested options is a little trickier, but you can use percent-encoded bracket notation. Let's say we have an API embed that sets up the social bar:

<!-- api_with_socialbar.html -->
  wistiaEmbed = Wistia.embed("g5pnf59ala", {
    plugin: {
      "socialbar-v1": {
        buttons: "playCount-embed-email",
        pageUrl: "https://wistia.com/blog",
        pageTitle: "Wistia's Blog"

The equivalent options on an iframe embed look like this:


Ugly, huh? That option string was constructed by following these steps:

First, use bracket notation to define the option names and values.

plugin[socialbar-v1][pageTitle]=Wistia's Blog

Next, percent encode each option name and value:


Note that percent encoding is slightly different from plain URL encoding in that URL encoding will change spaces to + and percent
encoding will change them to %20. We expect percent encoding, not plain URL encoding.

The options should be combined into one string and separated by
ampersands (&).


Last, add them back onto the iframe src.


Note that the first character after the hashed ID and before the options should be a question mark (?), not an ampersand (&). Setting it to an ampersand will break the whole embed!