Embed SVGs in your site

Picking the right embed mode for the playback you want.

Domotion outputs are standard SVG, so they embed in every browser via the usual mechanisms. But "the usual mechanisms" each have different behavior around CSS animations, accessibility, and same-origin policies. This page covers the trade-offs.

The four embed modes

Mode	Animations	Click events	Notes
`<img src="...">`	Yes	No	Best default. Lazy-loadable, accessible (with `alt`), small.
`<object data="...">`	Yes	Yes (links inside the SVG work)	Same-origin policy applies — the SVG runs in its own context.
`background-image: url(...)`	Sometimes	No	Most engines play the animation; `background` contexts can sometimes mute SVG `<style>`.
Inline `<svg>`	Yes	Yes (CSS reaches in)	No extra request. The SVG's IDs share scope with the host page — you'll need to namespace them.

Recommended: <img> with lazy loading

<img
  src="/assets/hero.svg"
  alt="Animated demo of installing the package and capturing a frame."
  width="800"
  height="320"
  loading="lazy"
  decoding="async"
/>

Specifying width and height attributes prevents content-shift while the image loads. loading="lazy" defers the fetch until the image is near the viewport — important for marketing pages that ship several SVG demos.

Inline SVG — when you need CSS to reach in

If you want to style the SVG from the host page (e.g. swap colors via CSS custom properties), inline it:

<figure>
  <!-- raw SVG markup pasted in here -->
  <svg viewBox="0 0 800 320" xmlns="http://www.w3.org/2000/svg">...</svg>
  <figcaption>Capture pipeline overview</figcaption>
</figure>

You'll want to:

Pass an idPrefix at capture time (or post-process the SVG) so its IDs don't collide with other SVGs on the page.
Strip the XML prologue (<?xml ...?>) — inline SVG doesn't need it.

Picking dimensions

Domotion writes width, height, and viewBox attributes on the root <svg>. The embed will:

Default to the width / height attributes when no CSS sizing is applied.
Scale to whatever width / height the host page sets via CSS or the <img> attributes — the viewBox ensures the content scales without distortion.

For responsive embedding, set width in CSS and let the SVG scale:

img.hero {
  width: 100%;
  max-width: 800px;
  height: auto;
}

Accessibility

Provide an alt on <img> embeds. Describe what the animation shows; screen readers won't otherwise surface the SVG content.
For inline SVG, add role="img" and an <title> child element near the top of the SVG.
Respect prefers-reduced-motion. Domotion's animations don't currently emit a guard for this — wrap your embed in a media query and serve a still SVG (a single captured frame) when motion should be reduced.

Reduced-motion fallback

<picture>
  <source media="(prefers-reduced-motion: reduce)" srcset="hero-still.svg" />
  <img src="hero-animated.svg" alt="..." />
</picture>

Caching

Treat the SVG like any other static asset: long cache headers (a year), content-hash the filename when it changes. Because the SVG is self-contained, swapping it is one HTTP fetch — no orphan font / image dependencies.