CodePen supports oEmbed, a clever system for making it super easy to embed rich content. Here's an example of oEmbed: just 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, just drop a Pen URL into the content area of an oEmbed-enabled site and it will be converted into an Embedded Pen automatically.

Here it is working in WordPress:

That's a much more compelling experience than just a link, right! Of course you can 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, 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?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:

See the Pen Junk Pile - #codevember by Matt DesLauriers (@mattdesl) on CodePen.

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.

An example of a site that supports oEmbed is Medium. Here's what an Embed looks like there:

HTTPS

You can make the oEmbed call over HTTP or HTTPS. Either way, the iframe we return will be HTTPS.

If you are getting a "mixed content warning" from an Embedded Pen on an HTTPS site, it's because that Pen links to an HTTP resource. To stop it, the Pen will need to link to that resource over HTTPS.

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:

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

Comments on CSS-Tricks