How to Embed CodeSandbox Demos in Your Blog Documentation

October 30, 2026

You embed a CodeSandbox demo with a URL in the form /embed/SANDBOX_ID?view=preview, dropped into an iframe. The view parameter is the whole trick: preview shows only the running app, editor shows code plus preview, split does both on wide screens.

Embedding source code in docs is easy. Embedding something that still runs in three years is where teams get surprised.

What are the embed URL parameters?

Parameter Effect Good default
view=preview Running app only Yes, for docs
view=split Editor + preview Tutorials with code
file=/src/App.tsx Opens a specific file When the point is that file
fontsize=12 Editor font size 12-13 for sidebars
hidenavigation=1 Hides the file tree Almost always
theme=dark Dark editor chrome Match your site

An iframe with hidenavigation=1 and view=preview looks like a native demo area. Add a fixed height around 400-500px and a border radius, and nobody knows it is an iframe.

How do you keep it from breaking on mobile?

Wrap it in a container with aspect-ratio instead of a fixed pixel height. A 500px iframe on a 375px-wide screen leaves the demo cut off at the bottom.

.demo-frame {
  width: 100%;
  aspect-ratio: 16 / 10;
  border: 0;
  border-radius: 8px;
}

Also set loading="lazy" on the iframe. Three live demos on one page will otherwise each boot a sandbox on page load, and your Lighthouse score drops by 15-25 points.

Does a live embed cost anything?

Yes, eventually. Sandboxes on the free tier sleep and cold-start in 3-15 seconds — a reader who sees a spinner for 10 seconds assumes the demo is broken.

Two strategies:

  • Pin the demo as a template. Templates boot faster and can be forked. Better public docs use this.
  • Ship a static screenshot with a “Copy code” button. Worst-case reader experience is a static image, which is honest.

Neither is free of maintenance. A pinned template that references an old dependency version will eventually fail to install, and your docs get a broken demo with no error you can see from the outside.

What makes a demo actually useful in docs?

Start with a working app, not a starter. If your embedded demo shows “Hello World” after a create-react-app scaffold, the reader learns nothing.

Strip it to the smallest code that shows the point — one file if possible. Every extra file is one more place the reader will look and get lost.

Name the sandbox after the doc page. CodeSandbox’s public search indexes titles, and demo traffic is real traffic. If the demo ranks for your feature name, put your docs link in the README field.

Where embeds backfire

  • WordPress. The block editor strips some iframe attributes; use a Custom HTML block and check sandbox attributes are preserved.
  • Inside a paywalled or authenticated page, iframes from codesandbox.io hit third-party cookie restrictions in Safari and can refuse to load.
  • Compliance-sensitive sites. An embed sends referrer and visitor data to CodeSandbox. If your privacy policy promises no third-party embeds, an iframe breaks the promise.
  • Docs that must render offline. PDF exports and view-source readers see an empty box.

A screenshot plus a link sidesteps all four. Use live embeds where the interactive part is the point, not as decoration.

Key Takeaways

  • Embed with /embed/?view=preview and hidenavigation=1; view=split for code-plus-preview.
  • Use aspect-ratio and loading="lazy" or mobile layouts break and page weight balloons.
  • Free-tier sandboxes cold-start in 3-15 seconds; pin a template for faster boot.
  • Strip demos to one file that demonstrates the specific point.
  • Check WordPress iframe sanitising and your privacy policy before adding live embeds.