How to Embed an Interactive Diagram in a Website or Documentation

To embed an interactive diagram, publish it and drop an iframe pointing at its embed URL into your page. In Diagramium that is /embed/<diagram-id>, with query options controlling autoplay, controls, narration, theme, starting step and branding. The reader gets the real player — they can step through it, pause and replay — instead of a screenshot that stops being true the moment the diagram changes. The part most people skip is the part that matters most for search and accessibility: a short text summary of the diagram underneath the frame.

Live interactive diagramUse the player controls to follow the steps

What is an API?Playing silently in this guideWatch with narration

What this diagram shows

1. A weather app on a phone is the client that starts the request.
2. It calls the endpoint, which is the API's front door, alongside published API documentation.
3. The request passes an API key check, a rate limiter and input validation before reaching business logic.
4. Business logic reads a cache of recent forecasts, then the forecast database, which is fed by a weather station feed.
5. The response is assembled; error codes cover the cases where it cannot be.
6. Logs and metrics record the call, and the forecast appears on the user's screen.

Why an embed beats a screenshot

A screenshot of a diagram has three problems. It goes stale silently — nothing tells you the picture no longer matches the system. It is unreadable when the diagram is dense, because it renders at whatever width the column allows. And it cannot be stepped through, so a fourteen-node architecture diagram lands as a wall.

An embed fixes all three: it always renders the current published version, it scales to its container, and the reader can walk it one step at a time. The cost is that an iframe is opaque — to a crawler, to a screen reader, and to anyone whose connection or content blocker stops it loading. That is a solvable problem, and the transcript section below is how you solve it.

An embedded diagram that nobody can read without JavaScript is a picture with extra steps. The text underneath is not optional.

How to embed one, step by step

1. Publish the diagram. Only published diagrams resolve at an embed URL — a private document returns an unavailable player, by design, so a draft cannot leak through a frame.
2. Get its id. It is the last segment of the diagram's own URL.
3. Build the iframe. The minimum is <iframe src="https://www.diagramium.com/embed/<id>"></iframe>. Use the "Copy embed code" action to get a complete snippet rather than assembling it by hand.
4. Add the delegated permissions. allow="fullscreen; autoplay". A cross-origin frame does not get these by default, so without them the full-screen control is dead and an autoplaying embed cannot start its own audio.
5. Add loading="lazy". On a page with several embeds this is the difference between one network request on first paint and one per frame.
6. Give it a real title. This is the frame's accessible name; "Interactive diagram" is weaker than "How a cheque clears — interactive process diagram".
7. Size it responsively. See below — a fixed pixel height is the most common mistake.
8. Write the text summary underneath. Non-negotiable if you want the page indexed on the diagram's content.

The URL options, and what they are for

Every option is optional and has a default, so a bare embed URL already works. The set is closed — an unrecognised value falls back to the default rather than being passed through.

• autoplay (default off) — start playing without a click. Off by default for a real reason: browsers block unmuted autoplay without a user gesture, so autoplaying a narrated diagram gives you a show that animates in silence, which is worse than a still frame with a play button. If you want autoplay on a page people are reading, pair it with narration=0.
• controls (default on) — the player's control bar.
• narration (default on) — voice, where the diagram has it.
• intro (default on) — the title beats before step one. Turn it off in a compact frame, where two full title slides eat most of the available space.
• startStep (default 0) — open on a particular step. Useful when the surrounding paragraph is about step four.
• loop (default off) — replay from the start when it finishes.
• notes — auto, side, bottom or hidden. In a short frame inside an article, hidden is usually right: the step guide reserves a whole column, and your prose is already doing that job.
• theme — light or dark.
• branding — full or minimal.
• origin — an optional allowlist of origins permitted to send commands to the frame. Worth setting if you publish on a shared or user-content domain.

The player embedded at the top of this page uses autoplay=1&narration=0&intro=0&startStep=1&notes=hidden&branding=minimal — silent, immediate, and giving the whole frame to the diagram.

Sizing it so it works on a phone

The commonest embed bug is a fixed height="600", which is fine on a laptop and produces a letterboxed sliver on a phone. Give the frame an aspect ratio instead and let the width drive it:

.diagram-embed {
  position: relative;
  width: 100%;
  aspect-ratio: 16 / 9;
}
.diagram-embed iframe {
  position: absolute;
  inset: 0;
  width: 100%;
  height: 100%;
  border: 0;
}

Two further notes from practice. Give the frame as much width as your layout allows — a diagram in a 640px column is roughly half the diagram it could be. And be aware that a lazily-loaded frame in a background tab may not receive resize events at all, so test by resizing with the tab in front.

Driving the player from your own page

The embed accepts a small, fixed set of commands over postMessage: play, pause, next, previous, goToStep and restart. That is the whole list — editing, authentication and administrative functions are absent rather than merely disabled, so there is no surface to get wrong.

It is enough to build the thing worth building: a documentation page whose prose is linked to the diagram, where the heading for step four advances the player to step four as the reader scrolls past it.

The text summary, and why it is the important part

Everything inside an iframe is invisible to the page that hosts it. A search engine indexing your documentation sees a box; it does not see the diagram's labels. A screen reader announces the frame's title and nothing else. A reader on a locked-down corporate network sees empty space.

So put the content in the page as well:

• A short step summary in real HTML — an ordered list of one line per step, in the page's own markup, server-rendered rather than injected by script. The block under the player on this page is exactly that.
• A descriptive frame title naming the specific diagram.
• A caption saying what the reader is looking at and what it will do — whether it plays silently, whether it loops.
• A link to the full presentation for anyone who wants it larger, or with narration.

This is the same reasoning behind alt text for images, and it is set out in the W3C's guidance on complex images: a diagram carrying substantial information needs a text alternative that conveys the same information, not a one-line label. For the frame itself, the iframe element reference covers the attributes that matter.

Diagrams that embed well

Frame size is a real constraint: what reads at full width can be illegible at 700 pixels. These hold up.

Best practices

• Silent by default on a reading page. narration=0 with autoplay, or no autoplay at all. Sound the reader did not ask for is the fastest way to get a tab closed.
• Hide the notes panel in short frames and let your prose carry the explanation.
• One embed per screenful. Several animations competing for attention is worse than none.
• Keep a still export as a fallback for PDF exports of your docs, email and print.
• Link the diagram's own page. Readers who want to explore or copy it should not have to hunt.
• Re-check embeds after you edit a diagram. The embed always shows the current published version — which is the feature, and also means a change you made for one context appears in every page that frames it.

Common mistakes

• No text alternative. The page ranks for nothing the diagram says, and readers who cannot load the frame get nothing at all.
• Fixed pixel height. Works on the machine you tested, letterboxes on every phone.
• Autoplay with narration on. Blocked by the browser, so the diagram animates silently and the reader assumes the audio is broken.
• Missing allow attribute. The full-screen button appears and does nothing.
• Embedding an unpublished diagram. The frame renders as unavailable — which is correct behaviour, and confusing if you were not expecting it.
• Embedding a dense diagram in a narrow column. Give it width, choose a diagram that suits the frame, or link out instead.

In short

One iframe, the right query options, a responsive aspect-ratio wrapper, and a text summary underneath. The options let you match the player to the page — silent and immediate for an article, controls and narration for a landing page, a specific starting step for a walkthrough. The summary is what makes the embed work for search engines, screen readers, and everyone whose frame never loads.

If you do not have a diagram to embed yet, the guide to making an animated diagram that explains itself covers getting the sequence and step notes right first — an embed of an unordered diagram is just a picture in a box. To find one to start from, browse the template gallery.

Questions people actually ask

How do I embed an interactive diagram in a website?

Publish the diagram, then add an iframe pointing at its embed URL, with allow="fullscreen; autoplay", loading="lazy" and a descriptive title. Wrap it in a container with an aspect ratio rather than giving it a fixed height, and add a short text summary of the steps below it.

Can I embed a diagram in documentation platforms like Notion or Confluence?

Anywhere that accepts an iframe or an embed URL, yes. Platforms that strip raw HTML usually have an embed block that takes a URL. Where a platform allows neither, fall back to an exported animated SVG, which works in a plain image tag.

Will an embedded diagram hurt my page speed?

Not meaningfully if you add loading="lazy", which defers the frame until it is near the viewport. Without it, every embed on the page opens a request on first paint.

Can search engines read an embedded diagram?

Not its contents. An iframe's content belongs to the framed document, not the host page, so anything inside it does not count as your page's content. That is precisely why a text summary in the host page's own HTML matters — it is the only version of the diagram the hosting page actually owns.

Can I control the embedded player from my page?

Yes, with postMessage. Six commands are accepted — play, pause, next, previous, goToStep and restart — which is enough to tie the player to a reader's scroll position or to your own buttons. Nothing beyond that list exists.

Does the embed track the people who view it?

No. Embedded players record nothing at all: the anonymous view counters that run elsewhere in the product are switched off for the lifetime of the frame, deliberately, because that traffic comes from other people's pages.