AnimationConfig

The argument shape for generateAnimatedSvg().

AnimationConfig

interface AnimationConfig {
  width: number;
  height: number;
  frames: AnimationFrame[];
  chrome?: {
    type: "terminal" | "browser" | "phone";
    title?: string;
    url?: string;
  };
  sharedDefs?: string;
}

width / height

number

SVG viewBox and outer dimensions for the animated SVG.

frames

AnimationFrame[]

Ordered list of captured frames. See below.

sharedDefs

string

SVG markup hoisted into the top-level <defs>. Frames can reference these IDs via <use href="#..."> — useful for glyph paths and other assets that repeat across frames.

AnimationFrame

interface AnimationFrame {
  svgContent: string;
  duration: number;
  transition?: {
    type: "crossfade" | "push-left" | "scroll";
    duration: number;
  };
  overlays?: Overlay[];
}

svgContent

string

The output of elementTreeToSvg(tree, w, h, idPrefix). Always pass a unique idPrefix per frame to avoid clip / gradient ID collisions.

duration

number (ms)

How long the frame is held visible at full opacity, before the transition to the next frame begins.

transition

{ type, duration }

The transition out of this frame. Defaults to { type: "crossfade", duration: 300 } when omitted. The last frame's transition is to the first frame (the loop wraps).

overlays

Overlay[]

Typing or tap effects that play on top of this frame for its duration. See Overlay types.

Transition types

crossfade — outgoing fades to 0 while incoming fades from 0; durations overlap so shared pixels stay visible. Default and recommended for "this state replaced that state".
cut — instant. No fade, no slide; duration is ignored. Use for beats where the page just updated (progress bar moved, line appeared, panel toggled).
push-left — outgoing slides off to the left, incoming slides in from the right.
scroll — both frames remain visible during the transition; opacity changes only at the end.

See Animation model for the trade-offs (especially: only all-crossfade sequences take the merge fast path).

Total duration

The animation's total duration is the sum of every frame's duration + transition.duration (transitions default to 300 ms when unset). The animation runs infinite by default and cannot be paused without scripting in the host page.

Example

const config: AnimationConfig = {
  width: 720,
  height: 420,
  frames: [
    {
      svgContent: frame0,
      duration: 1500,
      transition: { type: "push-left", duration: 400 },
      overlays: [{
        kind: "typing", text: "npm install domotion",
        x: 24, y: 32, fontSize: 14, color: "#e6edf3", speed: 40,
      }],
    },
    { svgContent: frame1, duration: 2500 },
    { svgContent: frame2, duration: 3000 },
  ],
};