motion-svg

npm install motion-svg

import { MotionSvgPlayer } from 'motion-svg/react';
import bundle from './animation.motionsvg.json';

function App() {
  return <MotionSvgPlayer data={bundle} width={400} height={300} />;
}

import { parseSvg } from 'motion-svg';

const scene = parseSvg(svgString);
// scene.viewBox   → { x, y, w, h }
// scene.paths     → SvgPath[] (all <path>, <rect>, <circle>, etc.)
// scene.groups    → SvgGroup[] (all <g> with children)
// scene.colors    → Record<id, color>
// scene.gradients → GradientDef[] (linear + radial)
// scene.metadata  → { xmlns, width, height, originalSvg }

import { createActor } from 'motion-svg';

const actor = createActor({
  id: 'my-actor',
  paths: [scene.paths[0], scene.paths[1]],
  origin: { x: 100, y: 100 },
  z: 1,  // optional z-order
});

import { generateShapePath } from 'motion-svg';

const rect = generateShapePath('rect', 100, 50);
const hex  = generateShapePath('polygon', 80, 80, { sides: 6 });

import { timeline } from 'motion-svg';

const tl = timeline(actor, {
  keyframes: [
    { at: 0, opacity: 0, position: { x: 0, y: 20 } },
    { at: 400, opacity: 1, position: { x: 0, y: 0 }, curve: 'easeOutCubic' },
  ],
});
// tl.id, tl.actorId, tl.keyframes, tl.duration

import { cubicBezier, getEasingFunction } from 'motion-svg';

// Custom cubic bezier (like CSS cubic-bezier)
const myEasing = cubicBezier(0.25, 0.1, 0.25, 1.0);

// Resolve by name
const fn = getEasingFunction('easeOutBack'); // (t: number) => number

{ at: 500, curve: { type: 'cubicBezier', x1: 0.4, y1: 0, x2: 0.2, y2: 1 } }

import { sequence } from 'motion-svg';

const combined = sequence(actor, {
  items: [
    { timeline: fadeIn },
    { timeline: slideUp, delay: 100 },
    { timeline: bounce, offset: 800 },
  ],
});

import { stagger } from 'motion-svg';

const timelines = stagger({
  actors: [card1, card2, card3, card4],
  keyframes: [
    { at: 0, opacity: 0, position: { x: 0, y: 20 } },
    { at: 400, opacity: 1, position: { x: 0, y: 0 }, curve: 'easeOutCubic' },
  ],
  stagger: 100,       // 100ms between each actor
  from: 'start',      // 'start' | 'end' | 'center' | 'edges'
});

import { lerpPath } from 'motion-svg';

const mid = lerpPath(
  'M0,0 L10,0 L10,10 Z',        // triangle
  'M0,0 L10,0 L10,10 L0,10 Z',  // square
  0.5
);

const morph = timeline(actor, {
  keyframes: [
    { at: 0, pathD: circlePath },
    { at: 1000, pathD: starPath, curve: 'easeInOutCubic' },
  ],
});

import { trigger } from 'motion-svg';

trigger(tl, { type: 'hover', reverse: true });
trigger(tl, { type: 'click', toggle: true });
trigger(tl, { type: 'loop', iterations: Infinity, direction: 'alternate', delay: 200 });
trigger(tl, { type: 'scroll', start: 0.2, end: 0.8 });
trigger(tl, { type: 'appear', threshold: 0.5, once: true });
trigger(tl, { type: 'manual' });

import { createPlayback } from 'motion-svg';

const ctrl = createPlayback({
  timeline: tl,
  trigger: triggerBinding,
  gradients: scene.gradients,
  onUpdate: (state, timeMs) => { /* apply state to DOM */ },
  onComplete: () => { /* all done */ },
});

ctrl.play();
ctrl.pause();
ctrl.stop();
ctrl.seek(500);
ctrl.reverse();

const unsub = ctrl.on('complete', (event) => {
  console.log(event.progress, event.currentTime);
});
// Event types: 'start' | 'play' | 'pause' | 'stop' | 'seek'
//            | 'reverse' | 'frame' | 'complete' | 'repeat'

import { getActorStateAtTime } from 'motion-svg';

const state = getActorStateAtTime(tl, 250, { gradients: scene.gradients });
// state.position → { x: 50, y: 0 }
// state.fill     → '#807f00' (smooth color lerp)

interface ActorState {
  position: Point;
  scale: number | Point;
  rotation: number;
  opacity: number;
  fill?: string;
  stroke?: string;
  strokeWidth?: number;
  strokeAlign?: StrokeAlign;
  blurRadius?: number;
  backdropBlur?: number;
  width?: number;
  height?: number;
  fillGradient?: GradientDef;
  strokeGradient?: GradientDef;
  pathD?: string;
}

// Hex → Hex
{ at: 0, fill: '#ff0000' }
{ at: 1000, fill: '#0000ff', curve: 'easeInOut' }
// At t=500 → '#800080'

// Gradient → Gradient
{ at: 0, fill: 'url(#sunrise)' }
{ at: 1000, fill: 'url(#sunset)', curve: 'easeInOut' }

// Color ↔ Gradient
{ at: 0, fill: '#ff6b6b' }
{ at: 1000, fill: 'url(#sunset)', curve: 'easeOut' }

{ at: 0, stroke: '#ff0000', strokeWidth: 2, strokeAlign: 'center' }
{ at: 500, stroke: '#00ff00', strokeWidth: 6, strokeAlign: 'outside', curve: 'easeOut' }

import { exportBundle } from 'motion-svg';

const json = exportBundle({
  scene,
  actors: [actor1, actor2],
  timelines: [tl1, tl2],
  triggers: [trigger1],
  variants: [{ name: 'idle', actorIds: ['a1'], timelineIndices: [0], triggerIndices: [0] }],
});

import { importBundle, getVariant } from 'motion-svg';

const imported = importBundle(jsonString);
// imported.scene, imported.actors, imported.timelines, imported.triggers, imported.variants

const variant = getVariant(imported, 'idle');
// variant.actors, variant.timelines, variant.triggers — or null

{
  "version": "1.1",
  "scene": { "viewBox": {...}, "paths": [...], "gradients": [...] },
  "actors": [{ "id": "logo", "pathIds": [...], "origin": {...} }],
  "timelines": [{ "actorId": "logo", "keyframes": [...] }],
  "triggers": [{ "timelineIdx": 0, "type": "hover", "reverse": true }],
  "variants": [{ "name": "idle", "actorIds": [...], "timelineIndices": [...] }]
}

import { importBundle, getVariant } from 'motion-svg';

const imported = importBundle(jsonString);
const names = imported.variants.map(v => v.name);

const idle = getVariant(imported, 'idle');
if (idle) {
  idle.actors;    // Actor[]
  idle.timelines; // Timeline[]
  idle.triggers;  // TriggerBinding[]
}

import { AnimationStore } from 'motion-svg';

const store = new AnimationStore();
store.set('actor-1', state);
store.setMany({ 'actor-1': state1, 'actor-2': state2 });
const snapshot = store.getSnapshot();
const actorState = store.getActorState('actor-1');
const unsub = store.subscribe(() => { /* re-render */ });
store.reset();

import { plugins } from 'motion-svg';

plugins.register(myPlugin);
plugins.unregister('my-plugin');
plugins.listPlugins();  // [{ name, version }]
plugins.clear();

import type { MotionSvgPlugin } from 'motion-svg';

const myPlugin: MotionSvgPlugin = {
  name: 'my-plugin',
  version: '1.0.0',
  hooks: {
    afterInterpolate(state, actorId, timeMs) {
      return { ...state, opacity: state.opacity * 0.8 };
    },
  },
  destroy() { /* cleanup */ },
};

import { springPlugin } from 'motion-svg/plugins';
import { plugins } from 'motion-svg';

plugins.register(springPlugin({
  stiffness: 120,    // higher = snappier (default: 100)
  damping: 8,        // higher = less oscillation (default: 10)
  mass: 1,           // higher = more inertia (default: 1)
  properties: ['scale', 'position'],
}));

import { customEasingPlugin, steppedEasing, elasticEasing } from 'motion-svg/plugins';
import { plugins } from 'motion-svg';

plugins.register(customEasingPlugin({
  easings: {
    stepped5: steppedEasing(5),
    superElastic: elasticEasing(1.5, 0.3),
    myCustom: (t) => t * t * (3 - 2 * t), // smoothstep
  },
}));

// Then use in keyframes:
// { at: 500, scale: 2, curve: 'stepped5' }

import {
  MotionSvgPlayer,   // Full player component
  MotionSvgActor,    // Single actor renderer
  MotionSvgCanvas,   // SVG canvas wrapper
  useMotionSvg,      // Control hook
  useActorState,     // Granular actor state hook
} from 'motion-svg/react';

const {
  data,           // ImportedBundle | null
  actors,         // Actor[]
  timelines,      // Timeline[]
  triggers,       // TriggerBinding[]
  actorStates,    // Record<string, ActorState>
  controllers,    // PlaybackController[]
  play, pause, stop, seek,
  playing,        // boolean
  variantNames,   // string[]
} = useMotionSvg(bundleJson, { variant: 'idle' });

<MotionSvgPlayer data={bundle} width={400} height={300} variant="idle" />

import { registerMotionSvg } from 'motion-svg/vanilla';
registerMotionSvg(); // or registerMotionSvg('my-player')

const el = document.querySelector('motion-svg');
el.bundle = bundleObject;     // set bundle programmatically
el.variant = 'dark';          // switch variant
el.play();
el.pause();
el.stop();
el.seek(500);
el.controllers;               // PlaybackController[]

import { importBundle } from 'motion-svg';

const json = await fetch('/my-animation.motionsvg.json').then(r => r.text());
const bundle = importBundle(json);

import { useState, useEffect, useRef, useMemo } from 'react';
import { importBundle, getActorStateAtTime } from 'motion-svg';

function AnimatedSvg({ bundleJson }) {
  const bundle = useMemo(() => importBundle(bundleJson), [bundleJson]);
  const [time, setTime] = useState(0);
  const rafRef = useRef();

  useEffect(() => {
    const start = performance.now();
    const tick = () => {
      setTime((performance.now() - start) % bundle.timelines[0].duration);
      rafRef.current = requestAnimationFrame(tick);
    };
    rafRef.current = requestAnimationFrame(tick);
    return () => cancelAnimationFrame(rafRef.current);
  }, [bundle]);

  const { scene, actors, timelines } = bundle;

  return (
    <svg viewBox={`${scene.viewBox.x} ${scene.viewBox.y} ${scene.viewBox.w} ${scene.viewBox.h}`}>
      {actors.map(actor => {
        const tl = timelines.find(t => t.actorId === actor.id);
        const state = tl ? getActorStateAtTime(tl, time, { gradients: scene.gradients }) : null;
        const ox = actor.origin.x, oy = actor.origin.y;
        const transform = state
          ? `translate(${state.position.x},${state.position.y}) translate(${ox},${oy}) rotate(${state.rotation}) scale(${typeof state.scale === 'number' ? state.scale : state.scale.x}) translate(${-ox},${-oy})`
          : '';
        return (
          <g key={actor.id} transform={transform} opacity={state?.opacity ?? 1}>
            {actor.paths.map(p => <path key={p.id} d={p.d} fill={state?.fill ?? p.fill} />)}
          </g>
        );
      })}
    </svg>
  );
}

import { getActorStateAtTime } from 'motion-svg';

const tl = bundle.timelines[0];
let startTime = performance.now();

function animate() {
  const elapsed = performance.now() - startTime;
  const timeMs = elapsed % tl.duration;
  const state = getActorStateAtTime(tl, timeMs, {
    gradients: bundle.scene.gradients,
  });
  // Apply state to DOM / canvas / WebGL / React state...
  requestAnimationFrame(animate);
}
animate();

import type {
  // Core
  Point, ViewBox, SvgPath, SvgGroup, Scene, SvgMetadata,
  // Color & Gradients
  ColorMap, ColorEntry, GradientStop, GradientDef,
  LinearGradientDef, RadialGradientDef,
  // Actor
  Actor, ActorConfig, ShapeType,
  // Animation
  Keyframe, TimelineConfig, Timeline, EasingName,
  EasingCurve, CubicBezierCurve,
  // Trigger
  TriggerType, TriggerConfig, TriggerBinding, LoopDirection,
  HoverTrigger, ClickTrigger, LoopTrigger, ScrollTrigger,
  AppearTrigger, ManualTrigger,
  // Bundle
  Bundle, BundleScene, BundleActor, BundleTimeline,
  BundleTrigger, BundleVariant, ExportConfig,
  // Playback
  PlaybackState, PlaybackController, PlaybackEventType,
  PlaybackEvent, PlaybackEventHandler,
  // Interpolation
  ActorState, InterpolateOptions,
  // Bundle I/O
  ImportedBundle, ValidationResult,
  // React
  UseMotionSvgOptions, MotionSvgInstance,
  // Path Morphing
  PathCommand, CubicSegment, NormalizedPath,
  // Orchestration
  SequenceConfig, SequenceItem, StaggerConfig, StaggerFrom,
  // Plugins
  MotionSvgPlugin, MotionSvgHooks, SpringConfig,
  SpringProperty, CustomEasingConfig,
} from 'motion-svg';

# 1. Fork & clone
git clone https://github.com/anthropics/motion-svg.git
cd motion-svg && pnpm install

# 2. Run tests
pnpm test

# 3. Make your contribution & open a PR