Customize CodePen embeds with parameters and oEmbed

The problem: your embedded Pen opens on the wrong tab

You copy a CodePen embed into your documentation or blog, publish the page, and notice the preview starts on the HTML tab when your readers need to see the CSS. Or the embedded iframe collapses to a default height and pushes content around. CodePen's default embed is convenient, but it does not adapt to your page's theme or content goals without extra parameters.

The useful takeaway: you can steer the embed with query parameters on the Pen URL, and you can fetch ready-made embed markup from CodePen's oEmbed endpoint if you are generating pages on a server. The trade-off is that these parameters are not a formal, versioned API, and the embed runs inside a sandboxed iframe, so some browser APIs are unavailable to the Pen.

1. Customize the embed with query parameters

CodePen's standard embed uses a script hosted at assets.codepen.io/embed/pen.js. The script looks for a <p> element containing a CodePen URL and replaces it with an iframe. You can append parameters to that URL to change what the iframe shows.

Common parameters:

• ?theme-id=dark — loads the dark theme instead of the default light theme.
• ?default-tab=css — opens the CSS editor tab first. Use html, css, js, or result.
• ?height=400 — sets the iframe height in pixels.
• ?editors=1010 — toggles editor visibility. Each digit corresponds to HTML, CSS, JS, and console; 1 shows and 0 hides.

Worked example: embed a Pen that opens on the CSS tab

Create a local file named embed-test.html. You do not need a CodePen account or server to run this; open it directly in a browser.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>CodePen embed test</title>
</head>
<body>
  <h2>Styled button example</h2>
  <p data-height="300" data-theme-id="dark" data-default-tab="css" data-slug-hash="abc123xyz" data-user="your-username" data-embed-version="2">
    <a href="https://codepen.io/your-username/pen/abc123xyz">View on CodePen</a>
  </p>
  <script async src="https://assets.codepen.io/embed/pen.js"></script>
</body>
</html>

Replace your-username and abc123xyz with a public Pen you own or can view. The data-* attributes map to the same options as query parameters. The script injects an iframe after the page loads.

Expected check: Reload the file. The iframe should render at about 300 pixels tall, use the dark theme, and show the CSS editor first. Open your browser's developer tools and inspect the <iframe> to confirm its src contains the parameters you set.

Risk: If the Pen is private or deleted, the iframe shows an error or blank area. Only embed public Pens unless you have a CodePen plan that supports private embeds.

2. Fetch embed markup with oEmbed

If you generate HTML on a server or in a CMS, you can call CodePen's oEmbed endpoint instead of pasting the client-side script. The endpoint returns JSON with an html field containing the embed markup, plus title, author_name, provider_name, and dimensions.

Run this in a terminal or browser, replacing the placeholder with a real public Pen URL:

curl "https://codepen.io/api/oembed?url=https://codepen.io/your-username/pen/abc123xyz"

Where to run: Any HTTP client, browser address bar, or server-side script. No special permissions are required for public Pens.

Expected check: The response should be JSON. Verify that type is rich, provider_name is CodePen, and html contains an iframe tag. Use the html value directly in your template.

Risk: oEmbed does not let you override every embed parameter through the API response alone. You may still need to append query parameters to the URL inside the returned html, or post-process the markup.

3. Limitations to plan around

• Sandboxing: The embedded Pen runs inside an iframe sandboxed from your page. Code that depends on window.opener, popups, or certain browser extensions will not work. Do not use embeds to test browser extensions or popup behavior.
• Layout shift: Because iframe height comes from ?height or CodePen's default, a tall Pen can push content down after it loads. Reserve space in your layout or set an explicit height.
• No formal contract: Query parameters are not documented as a stable public API. CodePen can change behavior without a changelog, so pin critical documentation embeds to a specific height and test them after site updates.
• Private Pens: Public embeds are free. Private embeds require a CodePen plan with the appropriate visibility settings.

4. How to verify before publishing

1. Open the public Pen in CodePen and click Embed to copy the generated HTML.
2. Paste it into a local HTML file or staging page.
3. Add ?theme-id=dark or ?default-tab=result to the Pen URL inside the embed and reload.
4. Confirm the theme and active tab change in the rendered iframe.
5. Call the oEmbed URL for the same Pen and confirm the JSON includes html and provider_name.

Closing

CodePen embeds are practical for showing live front-end code, but they work best when you set the theme, tab, and height explicitly. Start with the embed script for simple pages, use oEmbed when you generate markup on the server, and always check the iframe in a staging environment before you publish.