Can you embed an interactive demo in Docusaurus?

Yes. Docusaurus pages are MDX, so you can write an iframe directly in the file. Remember it is JSX, so style takes an object rather than a string, and the file must be .mdx rather than .md.

Where should demos go in documentation?

Getting-started pages first, and any page describing a multi-step UI flow. Avoid API reference pages, where readers want the parameter table, and avoid putting one on every page, which slows the site for people scanning for a single line.

What happens to embedded demos in versioned Docusaurus docs?

The page is versioned but the demo is not -- it keeps showing whatever the demo currently shows. Decide deliberately whether older doc versions keep a matching archived demo or link to the current one.

← Back to blog

How to Add an Interactive Demo to Docusaurus

August 19, 2026

Docusaurus pages are MDX, which means JSX works inside your Markdown and an iframe is simply an element you write.

That makes this the easiest kind of site to embed in, and the one where it is most worth building a small component rather than pasting markup repeatedly.

The quick version

In any `.mdx` file, write the iframe directly. Note that MDX is JSX, so attributes are camelCase and `style` takes an object: `style={{ width: "100%", aspectRatio: "16/10", border: 0 }}`.

A plain `.md` file will not do this. Rename it to `.mdx` if you need an embed in it.

Build a component instead

Create `src/components/Demo.jsx` wrapping the iframe with your sizing, lazy loading and a title, then use `<Demo id="..." />` throughout the docs.

This pays for itself the first time you change how demos are embedded, and it keeps the markup out of pages that should read as documentation.

Where demos belong in docs

Getting started -- the highest-value placement by a distance. Show what success looks like before someone starts.
Any page describing a multi-step UI flow, where prose is doing a job pictures do better.
Not on API reference pages. Developers reading a reference want the parameter table, and an embed is in the way.
Not on every page. Docs are scanned, and an embed on each one slows the whole site for readers looking for a single line.

Dark mode and versioning

Docusaurus ships a dark mode. A demo recorded against a light interface will sit as a bright rectangle in a dark page -- acceptable, but worth knowing before someone reports it as a bug.

Versioned docs are the real maintenance question: a demo embedded in a versioned page is frozen with that version's prose but not with the product. Decide deliberately whether old versions keep the old demo or point at the current one.

Frequently asked questions

Can you embed an interactive demo in Docusaurus?: Yes. Docusaurus pages are MDX, so you can write an iframe directly in the file. Remember it is JSX, so style takes an object rather than a string, and the file must be .mdx rather than .md.
Where should demos go in documentation?: Getting-started pages first, and any page describing a multi-step UI flow. Avoid API reference pages, where readers want the parameter table, and avoid putting one on every page, which slows the site for people scanning for a single line.
What happens to embedded demos in versioned Docusaurus docs?: The page is versioned but the demo is not -- it keeps showing whatever the demo currently shows. Decide deliberately whether older doc versions keep a matching archived demo or link to the current one.

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 →