The Complete Guide to Using WordPress Embeds

Share this article

WordPress embed Twitter

When you’re writing frequent posts on your WordPress website, you know that many times you’ll need to embed external content.

Whether that is a video from YouTube or Vimeo, a music clip from SoundCloud or Spotify, a Tweet or a Vine, a Flickr on an Instagram, there is not much to be done. You simply copy and paste the URL you want to embed into your WordPress article and that’s it.

This article will go through all of the details related to the WordPress embed and oEmbed functionality.

Why Does WordPress Need an Embed Feature?

One of the things which WordPress does really nicely when compared to other CMS’ I’ve used, is its ease to embed external media.

Without mentioning any names, embedding a simple a YouTube video into an article using one of the most popular CMS’s out there (other than WordPress) can be a nightmare of epic proportions.

Side note: this is a plea, not a dig. Embedding a YouTube video into an article should be a breeze in any CMS.

Why does this happen?

In reality, embedding external content is typically a potential security issue. Content is typically embedded using iFrames. An iFrame is simply a new “window” which is allowed to reference any external functionality.

If you want to embed a video from YouTube for example, you would need to embed the following syntax:

<iframe width="560" height="315" src="" frameborder="0" allowfullscreen></iframe>

So what’s the problem with that?

Nothing is actually wrong with this specific code. However, allowing anybody to enter iFrames into your posts is a serious security risk.

Why is it a security risk you may ask?

Whilst embedding a YouTube iFrame is fine, an iFrame can be used to reference ANY site. Users with malicious intent may actually embed an iFrame which references a site which is hosting malware.

To top it all off, iFrames can be hidden as 0 x 0 size pixel (an invisible dot), which makes it very hard to detect, at least with the naked eye.

Hence, why iFrames are discouraged in areas where user input is allowed.

In other CMS’, where the type of embed supported by WordPress is enabled, you can embed external media by doing one of the following:

  1. Use a third party plugin
  2. Allow embedding of iFrames (thus creating a potential security risk)

In fact, even using the WordPress embed function, only certain third party services are allowed. There’s an internal whitelist which determines which services are allowed and which ones aren’t. This is to mitigate any potential security issues.

How Does the WordPress Embed Feature Work?

There are a number of services which are supported by the WordPress Embed feature. You can find a full listing of services supported by Embed here.

The WordPress embed feature works by implementing the oEmbed API – essentially this is a way in which a consumer website (such as WordPress) can display embedded content from a provider (such as YouTube).

The consumer sends a HTTP request to the provider, and the provider replies with a JSON or XML HTTP response with the data structured in such a way as to allow the embedding of that media into the consumer website.

This is the request:

And this is the response:

{"html": "\u003ciframe width=\"480\" height=\"270\" src=\"https:\/\/\/embed\/M3r2XDceM6A?feature=oembed\" frameborder=\"0\" allowfullscreen\u003e\u003c\/iframe\u003e", "thumbnail_height": 360, 
"thumbnail_width": 480, 
"title": "Amazing Nintendo Facts", 
"width": 480, 
"height": 270, 
"type": "video", 
"provider_url": "https:\/\/\/", 
"thumbnail_url": "https:\/\/\/vi\/M3r2XDceM6A\/hqdefault.jpg", 
"author_name": "ZackScott", "
author_url": "https:\/\/\/user\/ZackScott", "version": "1.0", 
"provider_name": "YouTube"}

This is of course something which happens behind the scenes.

Embedding Media into WordPress

Now that we understand the functions behind WordPress, let’s see a few examples of media which can be embedded into a WordPress post.

You’ve probably done this already: embedding a YouTube video.

Rather than having to use the normal syntax associated with embedding a YouTube video, which is something similar to the following:

<iframe width="560" height="315" src="" frameborder="0" allowfullscreen></iframe>

You simple take the YouTube video URL and paste it into your post:
WordPress embed YouTube video

That’s it.

Just make sure it’s not actually converted into a hyperlink.

You are now able to see a preview of the video in the editor.

Once your post goes live, you’ll see the YouTube embedded in your post.

Next, let’s embed a Tweet into our post. Find the tweet you want to embed, click on the ellipses to get the link and then just post that into your WordPress post.

WordPress embed link to Tweet

The result will look something like this:

WordPress embed Twitter

This all happens automatically without needing to mess around with tags and blockquotes and iFrames and whatever else.

Let’s embed a SoundCloud file into our post. Once again, it’s just a question of finding the URL of the file you want to embed and pasting it into post.

You can see from the screenshot below, as soon as we entered the URL into the post, we immediately get a preview of the file which is going to be embedded into the post.

Embed SoundCloud WordPress

We could keep showing various other examples, but we’re sure you got the point.

Styling: Setting the (Maximum) Size of Embedded Media

In theory there is not much need for styling. The WordPress oEmbed feature is able to cater for most of the styling. It also handles responsiveness of your theme, so you don’t need to really worry about that either.

In practice though, there might be some need for you to actually size the media you are embedding.

The WordPress oEmbed functionality is in reality being handled by the [Embed] shortcode .

Using the [Embed] shortcode, you can set the maximum dimensions that a piece of media can take. These are not fixed, because of course we want the post to remain responsive.

Enable Media from Other Sites to Be Embedded

We mentioned a few paragraphs up that WordPress does not allow embedding of media from any site for security reasons.

However, if you want to embed media from a website which is not supported, you can of course do that.

To do this, you’ll need to add the site to the internal whitelist.

There are two ways of doing this, the method which you should use depends on whether the site supports the oEmbed API or not.

Adding Sites Which Support oEmbed API

In the functions.php file of your theme or plugin where you want to allow the embedding, call the following function to add a new site to the embed provider whitelist.


<?php wp_oembed_add_provider( $format, $provider, $regex ); ?>

For example,

<?php wp_oembed_add_provider( '*', '' ); ?>

If the media can be embedded via various URLs, you can use a Regular Expression to describe the various URLs possible. If we wanted to add our fictioutious site, TheNewTube with a regular expression, we could use the following:

<?php wp_oembed_add_provider( '#http://(www\.)?thenewtube\.com/watch.*#i', '', true ); ?>

Adding Sites Which Don’t Support oEmbed API

If the site you want to embed does not support oEmbed, you can still add them as a provider.

Again, through the functions.php file, you need to register the site using the wp_embed_register_handler

<?php wp_embed_register_handler( $id, $regex, $callback, $priority ); ?>

You’ll also need to provide a callback function, that would be used to generate the HTML required to embed the media.

The WordPress codex provides an example of how to do this to embed video from the Forbes website:


wp_embed_register_handler( 'forbes', '#http://(?:www|video)\.forbes\.com/(?:video/embed/embed\.html|embedvideo/)\?show=([\d]+)&format=frame&height=([\d]+)&width=([\d]+)&video=(.+?)($|&)#i', 'wp_embed_handler_forbes' );

function wp_embed_handler_forbes( $matches, $attr, $url, $rawattr ) {

    $embed = sprintf(
            '<iframe src="$s&format=frame&height=%2$s&width=%3$s&video=%4$s&mode=render" width="%3$spx" height="%2$spx" frameborder="0" scrolling="no" marginwidth="0" marginheight="0"></iframe>',

    return apply_filters( 'embed_forbes', $embed, $matches, $attr, $url, $rawattr );


If you need to do this for your site, it would be best to consult and hire a WordPress developer, just to make sure you don’t introduce any bugs which could break your site.

WordPress as an oEmbed Provider (Since WordPress Version 4.4)

Up till now we were only discussing WordPress as being a consumer of media from 3rd party sites, in reality WordPress was the oEmbed consumer.

WordPress as oEmbed Provider

Since 4.4, WordPress can also act as a Provider of oEmbed content.

What this means is that any public posts, or post types on your site can be embedded into third party websites via your own WordPress website (typically via their pretty permanent URL with an embed added to the end of the actual URL –

For security reasons, embeds reside in a sandboxed iFrame, however the content of the iFrame is a template that can be styled or replaced entirely by the theme on the provider site.

Functions and Hooks for Using Embeds

Here are the four most useful functions related to embeds:

Customizing the oEmbed Output

Similar to customizing any template file, the embed template from a post can be styled using embed_head and embed_footer to add custom code to the beginning and end of the embed template.

The X-WP-embed:true header will be also be sent when that template is used. This makes it easier to target embedded posts in any application which is consuming WordPress oEmbeds.


As we’ve seen in this article, the embed features of WordPress are quite rich in scope. Both for a writer and for a developer, there are plenty of ways in which WordPress embeds can be used to enhance content with embedded media.

Have you used WordPress embedding in any creative ways? We’d love to see and share your examples.

Frequently Asked Questions (FAQs) about Using WordPress Embeds

How Can I Embed a YouTube Video in WordPress?

Embedding a YouTube video in WordPress is quite simple. First, navigate to the YouTube video you want to embed. Click on the ‘Share’ button below the video, then click on ‘Embed’. Copy the HTML code that appears. Now, go to your WordPress post or page editor. Click on the ‘+’ button to add a new block and select ‘Custom HTML’. Paste the copied YouTube embed code here and click ‘Preview’ to see how it will look. Click ‘Publish’ or ‘Update’ to save your changes.

What Types of Media Can I Embed in WordPress?

WordPress supports a wide range of media types for embedding. This includes videos from platforms like YouTube, Vimeo, and DailyMotion, audio from SoundCloud, images from Instagram, tweets from Twitter, and posts from Facebook. You can also embed content from sites like Reddit, SlideShare, and more.

Why Isn’t My Embedded Media Displaying Properly?

If your embedded media isn’t displaying correctly, it could be due to several reasons. The source URL might be incorrect, the media might be private or protected, or there could be a conflict with your WordPress theme or plugins. Check the source URL and privacy settings of the media. If the problem persists, try disabling plugins one by one to identify any conflicts.

Can I Customize the Appearance of My Embedded Media?

Yes, you can customize the appearance of your embedded media to some extent. For example, with YouTube videos, you can control the display of video controls, related videos, and more using parameters in the embed code. However, customization options may vary depending on the media type and source platform.

How Can I Embed a Tweet in WordPress?

To embed a tweet in WordPress, go to the tweet you want to embed on Twitter. Click on the ‘…’ icon and select ‘Embed Tweet’. Copy the HTML code that appears. In your WordPress editor, add a new ‘Custom HTML’ block and paste the copied code. Click ‘Preview’ to see how it will look and ‘Publish’ or ‘Update’ to save your changes.

Can I Embed Media from Private or Protected Accounts?

Generally, you cannot embed media from private or protected accounts unless you have the necessary permissions. The media needs to be publicly accessible for WordPress to fetch and display it.

How Can I Embed a SoundCloud Audio in WordPress?

To embed a SoundCloud audio in WordPress, go to the track you want to embed on SoundCloud. Click on ‘Share’, then ‘Embed’. Copy the HTML code that appears. In your WordPress editor, add a new ‘Custom HTML’ block and paste the copied code. Click ‘Preview’ to see how it will look and ‘Publish’ or ‘Update’ to save your changes.

Can I Embed Media in WordPress Widgets?

Yes, you can embed media in WordPress widgets. Go to ‘Appearance’ > ‘Widgets’ in your WordPress dashboard. Add a ‘Custom HTML’ widget to your desired widget area and paste your embed code in it.

Why Can’t I See the ‘Embed’ Option on Some Platforms?

Not all platforms offer an ‘Embed’ option. In such cases, you can try copying the URL of the media and pasting it directly into your WordPress editor. WordPress will attempt to automatically embed the media.

Can I Embed Media in WordPress Comments?

Yes, you can embed media in WordPress comments. However, this feature needs to be enabled by the site administrator. Once enabled, you can paste the URL of the media directly into the comment box, and WordPress will automatically embed it.

David AttardDavid Attard
View Author

David is an inquisitive web designer who frequently shares his tips and tricks at CollectiveRay . When he's not blogging about web design, something he's been into for the last 12 years, he's usually dreaming about his next big thing.

ChrisBembedembed contentoEmbedWordPress
Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week
Loading form