# create-codepen

A browser library for embedding CodePen content via the CodePen embed API. Zero runtime dependencies, ESM-only, written with ES2023 syntax and built for baseline-widely-available browsers (Chrome 111+, Edge 111+, Firefox 114+, Safari 16.4+, iOS Safari 16.4+).

## Installation

```html
<script type="module">
  import { renderCodePen } from "https://unpkg.com/create-codepen@2";
</script>
```

## API Reference

### renderCodePen(options, selector?)

Renders a CodePen iframe. If `selector` is provided, embeds inside that element; otherwise opens in a new window.

A selector string that matches no element throws a `TypeError`. The matched host is replaced by `.code-pen-embed-wrapper` after rendering, so query the wrapper instead of the original element.

```ts
renderCodePen(options: CodePenOptions, selector?: string | HTMLElement): void
```

#### Parameters

| Parameter  | Type                    | Description                             |
| ---------- | ----------------------- | --------------------------------------- |
| `options`  | `CodePenOptions`        | Embed configuration (see Options below) |
| `selector` | `string \| HTMLElement` | Optional target element to embed into   |

#### Example

```html
<div id="pen-container"></div>

<script type="module">
  import { renderCodePen } from "https://unpkg.com/create-codepen@2";

  renderCodePen(
    {
      "slug-hash": "XWJPxpZ",
      user: "Mamboleoo",
      height: 300,
      "theme-id": "light",
      "default-tab": "js,result",
    },
    "#pen-container",
  );
</script>
```

---

### loadCodePens(selector?, options?)

Auto-embeds CodePens from DOM elements matching `selector` (default: `.codepen`). Scans for `data-*` attributes on elements and renders embeds accordingly.

```ts
loadCodePens(selector?: string, options?: CodePenDomOptions): void
```

#### Example

```html
<p
  class="codepen"
  data-slug-hash="XWJPxpZ"
  data-user="Mamboleoo"
  data-height="265"
  data-theme-id="light"
  data-default-tab="js,result"
>
  See the Pen <a href="https://codepen.io/Mamboleoo/pen/XWJPxpZ">Walkers - How to</a> by Louis
  Hoebregts (<a href="https://codepen.io/Mamboleoo">@Mamboleoo</a>)
</p>

<script type="module">
  import { loadCodePens } from "https://unpkg.com/create-codepen@2";
  loadCodePens();
</script>
```

#### Prefill embeds from the DOM

`loadCodePens()` also supports prefill embeds: put `data-prefill` on the container and the code in child elements with `data-lang`. The optional `data-prefill` JSON value only carries metadata.

```html
<div
  class="codepen"
  data-prefill='{"title":"My Pen","description":"A demo","tags":["demo"]}'
  data-height="400"
  data-default-tab="js,result"
>
  <pre data-lang="html">&lt;div id="root"&gt;&lt;/div&gt;</pre>
  <pre data-lang="scss">$color: #333; body { color: $color; }</pre>
  <pre data-lang="babel">console.log("hello");</pre>
</div>
```

Supported `data-prefill` JSON keys: `title`, `description`, `tags`, `html_classes`, `head`, `stylesheets`, `scripts`. Supported `data-lang` values:

- HTML: `html`, `xml`, `haml`, `markdown`, `slim`, `pug`
- CSS: `css`, `less`, `scss`, `sass`, `stylus`, `postcss`
- JS: `js`, `javascript`, `coffeescript`, `livescript`, `typescript`, `babel` (`vue` / `flutter` are sent as `js`)

`data-lang-version` adds the matching `<type>_version` option, and `data-options-autoprefixer` adds `css_prefix: "autoprefixer"`. Unknown `data-lang` values are ignored.

---

### openCodePens(selector?)

Opens CodePens from DOM elements in a new window instead of embedding.

```ts
openCodePens(selector?: string): void
```

#### Example

```html
<p
  class="codepen-open"
  data-slug-hash="XWJPxpZ"
  data-user="Mamboleoo"
  data-theme-id="light"
  data-default-tab="js,result"
>
  See the Pen Walkers - How to by Louis Hoebregts (@Mamboleoo)
</p>

<script type="module">
  import { openCodePens } from "https://unpkg.com/create-codepen@2";
  openCodePens(".codepen-open");
</script>
```

---

## DOM contract and re-rendering

`renderCodePen()` and `loadCodePens()` replace the matched host element with:

```html
<div class="code-pen-embed-wrapper" data-code-pen-rendered="true">…</div>
```

The wrapper keeps the host `id` (but not its `class` or inline `style`), so target it with `#your-id` or `.code-pen-embed-wrapper` afterwards.

Marked wrappers can be rendered again: calling `renderCodePen(options, "#your-id")` replaces the wrapper content instead of nesting another iframe. Do not keep references to the original host node.

---

## Options

### General Embed Options

Used by `renderCodePen()` and `loadCodePens()`.

| Option        | Type                      | Default    | Description                                                                                                                                                       |
| ------------- | ------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `slug-hash`   | `string`                  | —          | CodePen ID (e.g., `XWJPxpZ`). **Required** for non-prefill embeds                                                                                                 |
| `user`        | `string`                  | `"anon"`   | CodePen username                                                                                                                                                  |
| `default-tab` | `string`                  | `"result"` | Tab(s) shown initially: `"html"`, `"css"`, `"js"`, `"result"`, or comma-separated                                                                                 |
| `theme-id`    | `string \| number`        | `0`        | Theme ID (e.g., `"light"`)                                                                                                                                        |
| `pen-title`   | `string`                  | —          | Title for the embed iframe                                                                                                                                        |
| `open`        | `"true" \| "false"`       | `"false"`  | Only for `loadCodePens()`: open in a new window instead of embedding. `renderCodePen()` ignores it — it embeds with a selector and opens a new window without one |
| `editable`    | `"true" \| "false"`       | `"false"`  | Allow editing in embed                                                                                                                                            |
| `preview`     | `"true" \| "false"`       | `"false"`  | Show preview mode                                                                                                                                                 |
| `animations`  | `"run" \| "stop-after-5"` | —          | Animation behavior                                                                                                                                                |
| `zoom`        | `1 \| 0.5 \| 0.25`        | `1`        | Zoom level                                                                                                                                                        |
| `token`       | `string`                  | —          | Pen token for private pens                                                                                                                                        |

Any additional `data-*` attribute on a container becomes an option and is serialized into the embed URL (or prefill form). Only the documented names are meaningful; typos are forwarded verbatim.

Boolean-style options (`open`, `preview`, `editable`) are read as strings, matching `data-*` attribute values: use `"true"` / `"false"`.

---

### Style Options

Customize the embed iframe appearance.

| Option              | Type                          | Default     | Description                         |
| ------------------- | ----------------------------- | ----------- | ----------------------------------- |
| `height`            | `number \| string`            | `300`       | Iframe height in pixels             |
| `border`            | `"none" \| "thin" \| "thick"` | `"none"`    | Border style                        |
| `border-color`      | `string`                      | `"#000000"` | Border color                        |
| `tab-bar-color`     | `string`                      | `"#3d3d3e"` | Tab bar background color            |
| `tab-link-color`    | `string`                      | `"#76daff"` | Tab link color                      |
| `active-tab-color`  | `string`                      | `"#cccccc"` | Active tab background               |
| `active-link-color` | `string`                      | `"#000000"` | Active tab link color               |
| `link-logo-color`   | `string`                      | `"#ffffff"` | CodePen logo color                  |
| `class`             | `string`                      | —           | Additional CSS class for the iframe |
| `custom-css-url`    | `string`                      | —           | URL to custom CSS file              |

---

### Prefill Options

Create a new CodePen with inline code. Used inside the `prefill` property.

```ts
renderCodePen({
  prefill: {
    title: "My Pen",
    description: "Description here",
    html: "<div>Hello</div>",
    css: "body { background: #f0f0f0; }",
    js: "console.log('hi')",
  },
});
```

| Option               | Type                 | Description                                                         |
| -------------------- | -------------------- | ------------------------------------------------------------------- |
| `title`              | `string`             | Pen title                                                           |
| `description`        | `string`             | Pen description                                                     |
| `head`               | `string`             | HTML content for `<head>`                                           |
| `tags`               | `string \| string[]` | Tags for the pen                                                    |
| `html`               | `string`             | HTML content                                                        |
| `css`                | `string`             | CSS content                                                         |
| `js`                 | `string`             | JavaScript content                                                  |
| `html_pre_processor` | `string`             | HTML preprocessor (e.g., `"haml"`, `"pug"`, `"slim"`)               |
| `css_pre_processor`  | `string`             | CSS preprocessor (e.g., `"scss"`, `"less"`, `"stylus"`)             |
| `js_pre_processor`   | `string`             | JS preprocessor (e.g., `"babel"`, `"coffeescript"`, `"typescript"`) |
| `html_classes`       | `string \| string[]` | Classes for the `<html>` element                                    |
| `stylesheets`        | `string \| string[]` | External CSS URLs                                                   |
| `scripts`            | `string \| string[]` | External JS URLs                                                    |

---

## Complete Example

### Embed existing pen with custom styling

```html
<div id="embed"></div>

<script type="module">
  import { renderCodePen } from "https://unpkg.com/create-codepen@2";

  renderCodePen(
    {
      "slug-hash": "XWJPxpZ",
      user: "Mamboleoo",
      height: 400,
      "theme-id": "light",
      "default-tab": "js,result",
      border: "thick",
      "border-color": "#76daff",
    },
    "#embed",
  );
</script>
```

### Create new pen with prefill

```html
<div id="prefill"></div>

<script type="module">
  import { renderCodePen } from "https://unpkg.com/create-codepen@2";

  renderCodePen(
    {
      "default-tab": "js,result",
      prefill: {
        title: "React Demo",
        description: "A simple React example",
        html: '<div id="root"></div>',
        css: `body { font-family: system-ui; }`,
        js: `document.body.textContent = "Hello!";`,
        css_pre_processor: "scss",
        js_pre_processor: "babel",
      },
    },
    "#prefill",
  );
</script>
```

### Open in new window

```html
<button id="open-btn">Open CodePen</button>

<script type="module">
  import { renderCodePen } from "https://unpkg.com/create-codepen@2";

  document.querySelector("#open-btn").addEventListener("click", () => {
    renderCodePen({
      "slug-hash": "XWJPxpZ",
      user: "Mamboleoo",
      "default-tab": "js,result",
    });
  });
</script>
```

---

## License

[MIT](./LICENSE)
