WordPress and Wistia

WordPress is one of the most popular website builders out there, and we've got you covered on the tips and best practices for embedding Wistia videos on your site.

WordPress is an awesome platform for creating powerful websites. Here’s a guide to making Wistia and WordPress go together like PB&J. Or in some cases, PB&J and banana.

Getting Started - Wordpress.org or Wordpress.com?

Like Wistia’s favorite treat (donuts 🍩), WordPress comes in many flavors. Because of this, the “how” of embedding videos will vary based on the type of WordPress environment you’re using. Are you using a custom theme? What about plugins? We’ll cover all of this below, but we start with a very important question: are you using Wordpress.org, or Wordpress.com?

  • Wordpress.org is the fully customizable, self-hosted version of Wordpress. It comes with full support for themes and plugins, and requires paid hosting to use.
  • Wordpress.com is a free, blog style version of Wordpress with limited themes and no plugin support. It does not come with a custom domain, so your site’s URL would be something like “yoursite.wordpress.com” (unless you upgraded to a paid version).

We’ve found that most Wistia & WP users are on Wordpress.org, the self-hosted version with lots of options. Does your website have a custom domain? Then it’s probably on Wordpress.org.

Embedding on WordPress.org

WordPress.org, the self-hosted and super customizable version of Wordpress, is one of the most popular content management systems (CMS) for a reason. It offers a lot of site-building functionality to users at many different levels of web development experience, from novice to expert. When it comes to embedding Wistia-hosted videos, there are two main options that we recommend:

Alert
The embedding methods below are primarily intended for the default Wordpress editor. If you’re using a custom theme or plugin, that may change the rules around which embed codes you can and can’t use. Head on down to the section on working with themes and plugins.

Using the Standard embed on WP.org

The Inline, Standard Embed (or its close cousin, the popover) is the go-to option for embedding videos on your Wordpress site. This embed code uses HTML and Javascript to render a player on your webpage.

When you add a Standard embed to the page, make sure you’re using the text tab within the classic Wordpress editor. If you’re on the newer Gutenberg editor, use the Custom HTML block.

Using oEmbed on WP.org

Tip
Heads up! Before you can use oEmbed links on WordPress.org sites, you need to whitelist Wistia as an oEmbed provider which we describe below. This is a one-time step to enable the use of oEmbeds from Wistia.

oEmbed is a great option if you’d prefer less “code.” This formatting will convert the embed into a simple link, and when pasted into the WP editor it will dynamically request an embed code from Wistia. The end result is the same — an HTML and Javascript embed code on your page — but it’s a little neater on the surface since you’re only embedding a URL like this one:

http://fantastic.wistia.com/medias/60cf0ufhoo?embedType=async&videoFoam=true&videoWidth=640

To get an oEmbed URL for a video in your Wistia account, first choose the Inline, Standard embed and then select “Use oEmbed URL” under Options on the Embed & Share modal. Take a look-see:

That’ll give you an oEmbed URL, which you can add into the text tab of your page:

When you publish the page, the WP editor will convert the URL into an embedded video. It’s like magic. That said, before the magic happens you’ll need to whitelist Wistia oEmbeds in one of two ways.

The Wistia WordPress Plugin

By far the simplest way to enable Wistia oEmbeds in WP.org is to install the Wistia WordPress plugin. The primary job of this plugin is to handle the step of whitelisting Wistia as an oEmbed provider for Wordpress.org sites.

Install the Wistia WordPress plugin here, and you’ll be all set to start adding oEmbeds like it’s your job. Which it probably is.

Manually Add Wistia to the oEmbed provider whitelist

If you’d prefer not to add a new plugin, you can whitelist Wistia manually instead. Fortunately, adding Wistia as a trusted provider isn’t too difficult thanks to WordPress who have made this process fairly straightforward.

To start, you’ll want to use the wp_oembed_add_provider() function, explained in WordPress’s own documentation. In conjunction with some steps from our oEmbed help page here’s how this new provider rule will look:

php <?php wp_oembed_add_provider( '/https?:\/\/(.+)?(wistia.com|wi.st)\/(medias|embed)\/.*/', 'http://fast.wistia.com/oembed', true); ?>

From there it’s mostly a copy & paste job. Once you’ve added that to the functions.php file in your WordPress directory, you should be all set to use Wistia oEmbed URLs.

Wordpress Themes, Plugins, and Wistia Videos

Time for some Real Talk ™ — there are a ton of themes and plugins that exist for Wordpress. More are being developed each day, and many of them have options for using videos in new and creative ways. Unfortunately, not all of these tools are developed with inherent support for Wistia embeds.

We do our best to provide embedding options that are compatible with a variety of CMS platforms, but it’s nigh impossible to keep up with all the WP themes and plugins out there. Additionally, many video-specific plugins are built with support for only one or two hosting providers (lookin' at you, Youtube).

If the embedding options recommended on this help page aren’t working in your WP theme or plugin, there is a chance that tool does not support Wistia embeds. Here are some general pointers:

  • Try different embed types: Plugins can change the expected rules around embedding videos. If the Standard embed or the oEmbed link don’t work in a plugin, you might want to try our Fallback/iframe embed. While not typically recommended for WP.org sites, sometimes a plugin or theme may be built with iframe support.
  • Custom HTML options: If you’re not having any luck with the video-specific plugins, try using a Custom HTML or Code block if available. Sometimes we just need to find the right widget for accepting custom code.
  • Go back to the Classic editor: Often it’s the Visual Composer/Visual Editor of a theme that either won’t accept Wistia embed codes, or may modify and break them by mistake. If you’re having trouble embedding Wistia videos in a theme’s Visual Composer, try switching back to the classic WP editor to embed the video.
  • Check the documentation: Sometimes we can get our answers from the online docs for that theme or plugin. For example, if you’re using the Divi builder try Googling “embed video Divi.” Look up the support docs for tips on embedding video in the theme, and check if Wistia is mentioned as a hosting provider. If not, there’s a good chance they don’t support our embeds.
  • We’re here to help: When all else fails, email support@wistia.com or use our contact form. We’ll help to determine if Wistia embeds are supported and how best to implement them.

Lastly, if there is a theme or plugin you’re using but it doesn’t appear to support Wistia embeds, you might want to contact the developers who built it. As a user of their product, let them know that you’d like more support for Wistia-hosted videos. At the very least, they’ll know there is some demand for this functionality. At best, they might add support for Wistia!

Embedding on WordPress.com

If you’re using WordPress.com, we’ve got good news: adding videos to your posts is super easy, since Wistia is a default oEmbed provider for WP.com sites. In fact, oEmbed is the primary option for embedding in WordPress.com, specifically.

Just follow the same instructions above to get an oEmbed URL and paste it right into your WP.com post via the text tab. You may need to enter preview mode to render the link into a video. Publish the page and you’re all set!

Wistia on WordPress FAQ

What about oEmbed Popovers?

Wistia doesn’t currently offer an the “oEmbed” option within the Popover Embed tab. But that doesn’t mean it isn’t possible. In fact, creating a popover oEmbed is as easy as adding the popover=true parameter to your oEmbed link.

So for this Standard oEmbed:

http://fantastic.wistia.com/medias/60cf0ufhoo?embedType=async&videoWidth=640

We’d add the popover=true parameter onto the string of existing options:

http://fantastic.wistia.com/medias/60cf0ufhoo?embedType=async&popover=true&videoWidth=640Now we have an oEmbed URL that will result in a popover instead of an inline embed.

If you want to specify the size of the popover thumbnail (when playing, a popover video will always be responsive in its lightbox), change the videoWidth string. http://fantastic.wistia.com/medias/60cf0ufhoo?embedType=async&popover=true&videoWidth=200

Why isn’t my oEmbed URL converting into a video (WP.org)?

First, make sure you’ve followed the steps above for whitelisting Wistia as an oEmbed provider.

Next, when inserting an oEmbed URL in WP.org, make sure you are in the text/HTML editing tab. We recommend leaving an open line above and below the URL. These open lines will help ensure the URL is parsed properly as an oEmbed, instead of just a link or text.

If you switch from text/HTML to visual mode before publishing, the WP editor may add formatting tags around your oEmbed URL which can cause it to break. If you notice this happening, we suggest embedding the video in the text tab and then publishing the page directly, without switching back to visual mode first.

Why doesn’t a Fallback/iframe embed work (WP.org)?

We recommend the Standard embed for a specific reason — the WP editor will commonly modify iframe-based embed codes to “sandbox” them. This is a security measure; iframes reference an external URL and display it as a page-within-a-page, and sandboxing iframes helps to safeguard against malicious code being inserted there.

Think of an iframe as a portal to another webpage, and a Wistia iframe is a portal to a page with a video. Unfortunately, when Wistia embeds are sandboxed it prevents our scripts from executing within the WordPress page, therefore the player will not work as expected.

How to center my video?

If you want to center your video inside a div or column on your website, and you are using an oEmbed URL to embed your video, please use a second div with the style display: inline-block;, as seen here:

<div style="text-align: center;">
  <div style="display: inline-block;">
    http://fantastic.wistia.com/medias/60cf0ufhoo?embedType=async&videoWidth=640
  </div>
</div>

Video appearing smaller than it should be?

If you have larger resolution videos and they are appearing smaller or squished, access the WordPress admin control panel (Settings → Media → Maximum Video Embed Size) and set the max to the largest size of your video (’no limit' setting doesn’t work, it must be actual size). Some WordPress themes will also set a maximum width for content embedded with oEmbed. If you want to change that, check out How to Set oEmbed Max Width in WordPress 3.5 with $content_width.