How do you embed an interactive demo in Astro?

Write the iframe as plain HTML in any .astro file. Astro is HTML-first, so no JSX translation applies and no client directive is needed -- there is nothing to hydrate.

Does an embedded demo hurt an Astro site's performance?

It adds no JavaScript to your bundle since an iframe loads in its own context. It can still affect Core Web Vitals if it is unreserved or in the hero, so set an aspect ratio, lazy-load below the fold, and keep it out of the LCP slot.

Should I make a demo component in Astro?

Yes. A small Demo.astro component with sizing and lazy loading built in means every demo on the site behaves consistently, rather than depending on whoever pasted the markup.

← Back to blog

How to Add an Interactive Demo to an Astro Site

August 19, 2026

Astro sites are built to ship as little JavaScript as possible, which makes people cautious about third-party embeds.

An iframe is the one embed that does not undermine that: it adds no JavaScript to your bundle and loads in its own context.

The direct version

In any `.astro` file, write the iframe as plain HTML. Astro is HTML-first, so unlike MDX there is no JSX translation to think about -- `style="..."` as a string is correct here.

No client directive is needed. There is no component to hydrate, so the demo costs you nothing in Astro's own terms.

A component worth writing

Create `src/components/Demo.astro` taking the demo id and an optional title as props, with the sizing and lazy loading built in. Then `<Demo id="..." />` anywhere, including inside MDX content.

Consistency matters more than it sounds: it is how every demo on the site keeps its aspect ratio and lazy loading rather than depending on whoever pasted it.

Keep the Lighthouse score you chose Astro for

Reserve the aspect ratio, or you introduce layout shift into a site otherwise built to avoid it.
`loading="lazy"` below the fold, which keeps the demo out of the initial load entirely.
Do not put it in the hero. An iframe as your Largest Contentful Paint element undoes a lot of the work Astro does for you.
Measure it. Astro sites usually have room to spare, and knowing the actual cost beats assuming either way.

Content collections

If your marketing pages come from content collections, you can store a demo id as frontmatter and have the layout render the component when it is present.

That way adding a demo to a page is a one-line frontmatter change rather than an edit to the content body, which is much easier to keep tidy across dozens of pages.

Frequently asked questions

How do you embed an interactive demo in Astro?: Write the iframe as plain HTML in any .astro file. Astro is HTML-first, so no JSX translation applies and no client directive is needed -- there is nothing to hydrate.
Does an embedded demo hurt an Astro site's performance?: It adds no JavaScript to your bundle since an iframe loads in its own context. It can still affect Core Web Vitals if it is unreserved or in the hero, so set an aspect ratio, lazy-load below the fold, and keep it out of the LCP slot.
Should I make a demo component in Astro?: Yes. A small Demo.astro component with sizing and lazy loading built in means every demo on the site behaves consistently, rather than depending on whoever pasted the markup.

Keep reading

This is what Demorta does

Click through it — the same kind of demo you can record of your own product.

Try it on your own product

Record your first interactive demo free.

Five demos on the free plan, forever. No credit card, no trial countdown, no sales call. Install the Chrome extension, click through your product once, and you have a shareable link in about ten minutes.

Start free →