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 and Discourse.

That’s a much more compelling experience than just a link. You could use our Embed code also, which gives you more control, but it’s cool how easy this can be. It also can bring embeds to places our Embed code 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:

http://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

  1. We only allow /pen/ URL’s.
  2. You can’t customize the Embed. For instance, the iframe returned has our default theme and has 300px height.

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.

http://codepen.io/api/oembed/?url=http://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. If you end up doing that, and want to also use additional parameters to control things like the theme, let us know.

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('http://codepen.io/*/pen/*', 'http://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: