CodePen supports oEmbed, a clever system for making it super easy to embed rich content. Here’s an example of oEmbed: drop a YouTube video URL on its own line in (say) a blog post, and it will get replaced with an actual embedded video.

That’s just how CodePen oEmbed works, drop a Pen URL into the content area of an oEmbed-enabled site and it will be converted into an embedded Pen, automatically.

For example, Medium supports CodePen’s oEmbed. Paste a CodePen link and you’ll shortly see it transformed into an embed:

This works in other oEmbed supported places, like WordPress, Notion, and Discourse.

oEmbed can bring your Pens to other places where our standard embed code snippets might not work (because you aren’t allowed to post your own iframes or scripts), like user comment areas.

How It Works

The oEmbed spec is pretty simple really. You create an endpoint on your site that accepts one URL parameter: another URL.

In our case, it’s like this:

https://codepen.io/api/oembed?format=json&url=URL-TO-PEN-HERE

If that Pen is a valid Pen URL, it will return a JSON response, like:

{
  success: true,
  type: "rich",
  version: "1.0",
  provider_name: "CodePen",
  provider_url: "http://codepen.io",
  title: "Polygon hypnotism",
  author_name: "Luiz Otávio Carvalho",
  author_url: "http://codepen.io/superoak/",
  height: "300",
  width: "320",
  thumbnail_width: "384",
  thumbnail_height: "225",
  thumbnail_url: "https://s3-us-west-2.amazonaws.com/m.cdpn.io/screenshot-coming-soon-small.png",
  html: "<iframe id="cp_embed_dPrEvP" class="cp_embed_iframe" style="width: 100%; overflow: hidden;" src="https://codepen.io/superoak/embed/preview/dPrEvP?height=300&slug-hash=dPrEvP&default-tab=result&host=http%3A%2F%2Fcodepen.io" width="300" height="300" frameborder="0" scrolling="no"></iframe>"
}

We return a “rich” content type, meaning supporting sites should use the HTML we return to display the content. That HTML, in our case, is an HTTPS <iframe> with the Embedded Pen. This is a bit different than our regular Embed code, which is a <script> that replaces a <div> with the <iframe>. What is cool about that is that the fallback content is still useful. Meaning if the site’s content is read through RSS or JavaScript is disabled/broken or something, there is still meaningful content and links in there.

Sites that support oEmbed will take that HTML we return and drop it onto the page.

oEmbed Uses a Preview State

oEmbed automatically use the Click-to-Play Preview State, which is normally an optional feature of Embedded Pens. We do that on purpose, because often oEmbed is used on sites like forums, chat rooms, comment threads, etc, where it’s kind of open season on what gets posted (not quite the same as an author explicitly choosing Pens to appear).

Here’s a live example:

(Above is actually using our Gutenberg plugin, because these docs are in WordPress/Gutenberg).

The Click-to-Play Preview State does two useful things:

  1. Prevents potentially obnoxious things from happening automatically, like alert()s, sounds, animations, etc. We want those things to work in embeds, it should just be possible to only allow them after an explicit interaction.
  2. Is lighter weight than the full embed, so you could have tons of them on a single page without it affecting performance nearly as much as full on Embeds.
  3. With a “normal” embed (non-oEmbed), you can have a Click-to-Play embed and also have one of the code panels open, but with oEmbed it defaults to showing the result panel full frame.

JSONP

This isn’t directly related to oEmbed, but if you want a similar JSON response, only wrapped in a function all (JSONP), we use the same endpoint:

https://codepen.io/api/oembed/?url=http://codepen.io/FWeinb/pen/wjzyH&format=js&callback=coolDude

This URL will return:

coolDude({
  success: true,
  type: "rich",
  version: "1.0",
  provider_name: "CodePen",
  provider_url: "http://codepen.io",
  title: "Polygon hypnotism",
  author_name: "Luiz Otávio Carvalho",
  author_url: "http://codepen.io/superoak/",
  height: "300",
  width: "320",
  thumbnail_width: "384",
  thumbnail_height: "225",
  thumbnail_url: "https://s3-us-west-2.amazonaws.com/m.cdpn.io/screenshot-coming-soon-small.png",
  html: "<iframe id="cp_embed_dPrEvP" src="https://codepen.io/superoak/embed/preview/dPrEvP?height=300&slug-hash=dPrEvP&default-tab=result&host=http%3A%2F%2Fcodepen.io" scrolling="no" frameborder="0" height="300" allowtransparency="true" class="cp_embed_iframe" style="width: 100%; overflow: hidden;"></iframe>"
});

Limitations of oEmbed

oEmbed Pens use our default theme and are not customizable. The editable feature is not available on oEmbed Pens.

For basic theme options and tab selection, use our standard Embedded Pens. PRO members have full control over the embed appearance with PRO embed themes.

Height Adjusting

If you know you want the response to have a taller iframe, you can pass height=xxx in the URL params and it will return the the proper code to have the iframe be that tall.

https://codepen.io/api/oembed/?url=https://codepen.io/FWeinb/pen/wjzyH&format=json&height=500

You have to do this at the endpoint level. The point on your end when you call our oEmbed API endpoint. It can’t be done on a per-Pen level, unless you somehow write the code yourself to parse that height parameter out of the URL the author provides and insert it into the API call URL.

Specifics about Using oEmbed in WordPress

WordPress (hosted .com and self-hosted .org) both support oEmbed. But they work off an internal “whitelist” of sites. Flickr and YouTube are among the list of about 20. WordPress.com supports CodePen Embeds by default, but the self-hosted WordPress.org sites do not (hopefully soon).

It’s easy to add support to your self-hosted site though. It’s a one liner in your theme’s functions.php file:

wp_oembed_add_provider('https://codepen.io/*/pen/*', 'https://codepen.io/api/oembed');

Or perhaps even better, there is a plugin to enable support. This is a good way to go, so that support persists no matter what theme you use.

That’s it! Now it will work.

Minor notes about WordPress usage

  • If you’re blogging in Markdown, oEmbed will only work through Jetpack-enabled Markdown (not third-party Markdown plugins).
  • oEmbed only works through Post/Page content in WordPress, but you can bring it to comments as well.
Was this article helpful?
YesNo