Prefill Embeds

CodePen Prefill Embeds allow you to enhance code that you are already displaying on your own website and transform it into an interactive environment.

Here's why Prefill Embeds are useful: say you have a blog or documentation site displaying important bits of code within <pre><code> tags. Perhaps you need to show a bit of HTML, CSS, or JavaScript. Here's an example bit of HTML you might show:

The embed code is very easy to work with. You leave your <pre> blocks on the page (progressive enhancement! SEO! RSS friendly!) then wrap them in a <div> with attributes that control the embed, like this:

You can pass in a block of HTML, CSS, and JavaScript (all optional), and each supports all of the relevant preprocessors for those languages that CodePen supports. (e.g. Markdown, SCSS, Babel, etc.) Prefill embeds also support all of the options regular Embedded Pens do, like themes, setting the default tabs, and external resources.

Here's an example with one possible configuration of a complete set of options, including using preprocessors, setting metadata, and loading external resources:

Note the very special encoding for head value. You'll need to encode any special characters passed there, including angle brackets and, because it needs to be valid JSON, encoded single quotes within the HTML.

What goes on the wrapper element

Like all our embeds, we rely on a class="codepen" on a wrapper element to enhance that element into a CodePen Embed. For Prefill Embeds, you control some of that with a variety of data-* attributes.

The main required one for prefill embeds is data-prefill, which can be just that, or can have the value of a JSON string to send in additional code and options.

There are more data-* attributes that control other things, here's the others:

data-attribute

value

example

default

data-height

Integer

"400"

"300"

data-theme-id

Integer or keyword

"13289", "light", or "dark"

no value, default gray theme

data-editable

Boolean

"true"

"false"

data-default-tab

String

"html,result"

"result"

What goes on the <pre> blocks

HTML blocks are like this:

<pre data-lang="html">
<!-- *Escaped* HTML goes in here. -->
</pre>

The data-lang can be: html, slim, haml, markdown, or pug

CSS blocks are like this:

<pre data-lang="css" data-options-autoprefixer="true">
</pre>

The data-lang values can be css, scss, sass, less, stylus, and postcss. Note the extra data-options-autoprefixer which can be set to true if you want to use Autoprefixer.

JavaScript blocks are like this:

<pre data-lang="js">
</pre>

The data-lang values can be js, babel, typescript, coffeescript, or livescript. Note that in order to us JSX you'll need to use babel, and you'll need to escape those angle brackets.

What could go wrong?

This is a pretty complicated HTML API! The escaping of code could trip you up. If you're displaying <pre> blocks of code on your site, you've probably got that code escaping thing already handled though. The trick then is making sure that anything you pass as the {} of data-prefill="{}" is valid JSON, as we parse that directly. Probably doesn't hurt to validate the JSON.

Enhance <pre> blocks into editable embeds on click (or on any other event)

To do this, set up your prefill embeds as you normally would, only don't use the class name codepen on the wrapping <div>. Instead, you can use something of your choosing, like codepen-later.

Then on whatever action you choose (could be something like a click, or a scroll into view event, some kind of timeout, or whatever you can think of), you call our global API to convert them into embeds. Here's an example of a button click to load them: