The Ultimate Guide to Embedding Content in WordPress with oEmbed

The Ultimate Guide to Embedding Content in WordPress with oEmbed

The internet sure is a social place. It feels like sharing videos, posts, tweets, photos, memes and music has always been the norm. And thanks to oEmbed, the norm is super easy with WordPress.

When you share media from an external source and place it on your own site, it’s called embedding and it’s normally achieved with some code. oEmbed is the latest format for embedding. Its API allows you to share content by simply pasting the URL of any resource you want to embed without the need for code.

It’s quick and easy to use thanks to the WordPress’ support for the format. Just paste a link to a video or tweet right into a post or page and it will be automatically embedded for you with great results every time and no need to for extra CSS styling.

Here’s what you need to know about embedding media into your WordPress posts and pages and some extra plugins to help give even more power to your embeds.

In this post, we’ll cover:

Say Goodbye to iFrames

I remember first learning to code when I was 10 when my family finally got a then decent computer that didn’t run on DOS. Instead, it ran on Windows ’95. I shudder at the thought of that system now seeing how far technology has come since then and remembering what embedding content looked like back then also gives me the same effect.

HTML iFrames (inline frames) were a common way to embed content then and this hasn’t changed all that much even today.

An whole site is displayed within another site using an iFrame.
Yeah, how about let’s not and say we did use an iframe to display an entire site, but let’s also not say we did.

The sole purpose of an iFrame is to embed an entire document which isn’t always ideal. It all starts by creating a new post or page in your dashboard through Posts > Add New or Pages > Add New. Navigate to the text editor and type in your basic code for creating an iFrame similar to the example below:

While there are many properties you can enter into an iFrame tag, these are just three that are among the most used. The width and height options set the size of the iFrame and src sets the content of the iFrame via a URL.

When HTML was updated to version five, there was also an additional tag that was added which could be used for embedding media as well. It’s a bit of an upgrade from the traditional iFrames, but can be used in much the same way.

The embed tag creates a container, which you can then style with CSS. It also doesn’t require a closing tag and all major browsers support it.

While you absolutely can add an iFrame and HTML5 tags to your page or post editor, there’s an even faster and easier way to embed content into WordPress: Enter oEmbed.

Embedding With oEmbed

Embedding media into WordPress posts and pages has never been easier largely because of the addition of oEmbed, which allows you to bring content like videos, images, tweets, audio and more from a different site into your own site. This is all done by copy and pasting the URL of the content directly into the editor.

That’s it.

A URL is rendered in the visual editor as the video that is displayed after the post is published.
Adding media is quick and easy with oEmbed.

It looks great in the visual editor, but it looks even better on the front-end. Possibly the best part is that oEmbed doesn’t require any additional styling.

A video is displayed well in a post on the public-facing site.
oEmbed takes care of all the technical aspects of embedding.

Embedding media into your site looks as though you did style it to fit into your theme. Plus, no matter what kind of media you add, it consistently looks great even on mobile screens.

You won’t have to worry whether your content can remain responsive since oEmbed already has its bases covered and changing your color scheme is also not a problem.

You could also change your color scheme and your media can still look great even with a darker background, for example.

A tweet is displayed well on a mobile screen.
Keeping your site responsive isn’t a problem with oEmbed.

You are also able to embed a wide variety of media types including documents and slideshows. They’re displayed dynamically so your visitors can interact with them.

If you display a magazine from Issuu, for example, a user can click to turn the pages as you would a book and select a larger view.

A book is dynamically displayed in a post on the front end.
Documents also display well with oEmbed.

The only two requirements are that the URL be placed on its own line and it’s not hyperlinked just as in the example below:

Once you have pasted the URL of the media you want to embed into the visual editor, it appears after it’s processed and displays exactly how it should appear after you publish your post or page.

There’s also another way you can use oEmbed and that’s with a simple shortcode. Media is displayed the same way, but you can add simple styling options.

For example, you could adjust the width and height just as you would with an iFrame. The biggest difference is the link is included between the tags, not inside them.

Media is displayed the same when using shortcodes.
Media is displayed the same when using shortcodes.

It works the same as most other shortcodes so it’s easy enough to use. The oEmbed shortcode does have a closing tag so don’t forget to include it when you’re embedding media to your site.

Here’s an example of the structure you would use, and in this case, a YouTube video is being embedded:

You can embed content from many sources, though, you should keep in mind that you can only embed media from whitelisted sites by default.

The reason your choices are limited is to reduce the security risk that comes from untrusted sources when malicious content is injected into your site if you decide to embed it. By giving you permission to embed content from only approved, credible sources, you can rest easy knowing your site can remain secure.

Here are the currently whitelisted sites with the media types for each that are accepted at the time this was written:

That isn’t to say you have to stick with these sites. It’s possible to add and remove the accepted oEmbed sites.

FREE EBOOK
Your step-by-step roadmap to a profitable web dev business. From landing more clients to scaling like crazy.

By downloading this ebook I consent to occasionally receive emails from WPMU DEV.
We keep your email 100% private and do not spam.

FREE EBOOK
Plan, build, and launch your next WP site without a hitch. Our checklist makes the process easy and repeatable.

By downloading this ebook I consent to occasionally receive emails from WPMU DEV.
We keep your email 100% private and do not spam.

Adding and Removing oEmbed Sites

If you want to whitelist a site to embed its content you need to be sure that it has oEmbed enabled. If you’re not sure, you can check the official oEmbed site’s Provider list.

Once you know which provider you want to whitelist, open your wp-includes/embed.php file and call the wp_oembed_add_provider() function in this format:

The $format string should include the proper structure of the URL with a wildcard asterisk to represent the pretty permalink portion of the URL where the media can be found. The $provider string is the base URL of the oEmbed provider and the $regex boolean that sets whether or not the format parameter is using a regular expression. If set to true, this means it’s a regular expression. The default and other option is false which means it’s not a regex.

When you put it all together and enter the URL’s you need, the result should look similar to this:

If you would rather not code your own PHP, you’re in luck. There’s an excellent oEmbed code generator at GenerateWP. All you need to do is fill in the fields with the appropriate URL’s and click the Update Code button to reveal the code that you can then copy and paste into your embed.php file.

If the site you want to add doesn’t have oEmbed enabled, not to worry. You can still add it with the wp_embed_register_handler() function in your theme’s functions.php file. The structure you need to follow to register an embed handler looks like this:

The $id string needs to be a unique identifier for internal use. The $regex string is the regular expression that checks if your handler should be used for a URL. The callback function in this structure – labelled as $callback in this example – is what’s called if the regular expression is matched and the $priority integer is used to establish the order of the handlers when they’re tested. The default is 10 and handler with the same integer are tested in the order they were added to the action while a lower number means the handler is tested earlier than others in the action.

The WordPress Codex also has a great example of what this function should look like if you wanted to register Forbes videos to oEmbed. You can use it as inspiration.

If you would rather not support an oEmbed site, you can remove it with the wp_oembed_remove_provider function in your site’s wp-includes/media.php file. Here’s the structure you need to follow:

The $format string is the URL of the oEmbed site you want to remove. You can get this from the wp-includes/class-oembed.php file. For example, if you wanted to remove WordPress.tv from the list (but why would you, anyway?) you would add this to your media.php file:

If you would rather not touch and code at all, there are plugins you can install as a suitable alternative.

Achieving oEmbed with Plugins

These plugins are updated fairly frequently and have interesting capabilities to offer. While not all the plugins on this list were necessarily made for Multisite, they should work just fine on your network.

oEmbed Manager

oEmbed Manager
oEmbed Manager

This plugin lets you control whether other websites can or cannot embed your content and conditionally allow or disallow the display of embedded content on your site.

It also lets you perform various oEmbed finetuning and optimization functions (e.g. list, clear and update/create oEmbed cached items) and integrates with various privacy and compliance plugins.

More info: oEmbed Manager

Embedly

Embedly
Embedly

Embedly extends the providers that are available to you by default to over 300 different sites including Google Maps, Dribbble, Skitch and deviantART to name only a few. This is also the plugin you may want to use if you prefer not to touch any code, but want to add more oEmbed providers to your site.

It installs as easily as most other plugins and you can even customize the styling if you want. To use it, you just need to add a URL to your posts and pages just as you normally would.

More info: Embedly

Add External Media

Add External Media
Add External Media

This plugin adds the files you want to embed into your site’s media library to use as if you were the one who uploaded them to your site, but you still get all the regular space-saving benefits you would with regular oEmbed. Plus, it installs like most other plugins so you can get started quickly.

More info: Add External Media

Wrapping Up

Embedding content into your WordPress posts and pages couldn’t be easier with oEmbed. The internet and WordPress have come a long way since its humble beginnings and you are now able to save some space while still being able to share all the videos, images and projects you want.

While adding and removing providers to the oEmbed whitelist for your site can be a bit challenging if you’re not familiar with PHP, there’s help on the way. Daniel Pataki has put together a five-part series to help you learn PHP, even if you don’t have much experience with it. Check out the first part of the series to get started right away: WordPress Development for Beginners: Getting Started.

Editor’s Note: This post has been updated for accuracy and relevancy. [Originally Published: Jan 2016 / Revised: February 2022]

Have you already used oEmbed on your WordPress site? If not, could you see yourself using it all the time? What sites would you like to see supported? Feel free to share your thoughts in the comments below.

Tags:

Jenni McKinnon Jenni has spent over 15 years developing websites and almost as long for WordPress as a copywriter, copy editor, web developer, and course instructor. A self-described WordPress nerd, she enjoys watching The Simpsons and names her test sites after references from the show.