Motion() Factory

import { Motion } from "@motion.page/sdk";

<script src="https://cloud.motion.page/sdk/latest.js"></script>
<script>
  // window.Motion is available globally
  Motion("fade", ".box", { from: { opacity: 0 }, duration: 0.6 }).onPageLoad();
</script>

// 1. Retrieve an existing timeline by name
Motion(name: string): Timeline

// 2. Single-animation timeline — one target, one config object
Motion(name: string, target: TargetInput, config: AnimationConfig): Timeline

// 3. Multi-step timeline — array of animation entries
Motion(name: string, animations: AnimationEntry[]): Timeline

import { Motion } from "@motion.page/sdk";

// Create and play immediately
Motion("hero", "#hero", {
  from: { opacity: 0, y: 40 },
  duration: 0.8,
  ease: "power2.out",
}).play();

// Create and play on page load
Motion("cards", ".card", {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  stagger: 0.08,
  ease: "power2.out",
}).onPageLoad();

// Retrieve an existing timeline later by name
const tl = Motion("hero");
tl.pause();

const counter = { value: 0 };

Motion("count-up", counter, {
  to: { value: 1000 },
  duration: 2,
  ease: "power2.out",
  onUpdate: () => {
    document.querySelector("#counter")!.textContent =
      Math.round(counter.value).toString();
  },
}).onPageLoad();

interface AnimationConfig {
  from?:              AnimationVars;
  to?:                AnimationVars;
  duration?:          number;
  delay?:             number;
  ease?:              string;
  stagger?:           number | StaggerVars;
  repeat?:            number | RepeatConfig;
  split?:             SplitType;
  mask?:              boolean;
  flap?:              FlapConfig;
  fit?:               FitConfig;
  axis?:              'x' | 'y';
  onStart?:           () => void;
  onUpdate?:          (progress: number) => void;
  onComplete?:        () => void;
  onRepeat?:          (repeatCount: number) => void;
  onReverseComplete?: () => void;
}

path: {
  target:   string | Element;  // CSS selector, Element, or raw path data (M/m commands)
  align?:   string | Element;  // Align bounding box to this element
  alignAt?: [number, number];  // Origin point [x%, y%]; default [50, 50]
  start?:   number;            // Path start fraction 0–1; default 0
  end?:     number;            // Path end fraction 0–1; default 1
  rotate?:  boolean;           // Auto-rotate along the path tangent
}

to: { '--accent-color': '#9966FF', '--spacing': '24px' }

// ✅ from-only — SDK fills in opacity:1, y:0 from the element's CSS
Motion("reveal", ".card", {
  from: { opacity: 0, y: 50 },
  duration: 0.6,
}).onPageLoad();

// ✅ to-only — start at natural state, hover to raised state
Motion("lift", ".card", {
  to: { y: -8, boxShadow: "0 12px 24px rgba(0,0,0,0.15)" },
  duration: 0.3,
}).onHover({ each: true, onLeave: "reverse" });

// ✅ both — parallax where neither endpoint is the natural state
Motion("parallax", ".bg", {
  from: { y: -60 },
  to:   { y: 60 },
}).onScroll({ scrub: true });

// ❌ redundant — opacity:1 and y:0 are natural defaults
Motion("bad", ".card", {
  from: { opacity: 0, y: 50 },
  to:   { opacity: 1, y: 0 },
}).onPageLoad();

Motion("intro", [
  { target: ".hero-title",    from: { opacity: 0, y: 40 }, duration: 0.7, ease: "power2.out" },
  { target: ".hero-subtitle", from: { opacity: 0, y: 30 }, duration: 0.6, ease: "power2.out" },
  { target: ".hero-cta",      from: { opacity: 0, y: 20 }, duration: 0.5, ease: "power2.out" },
]).onPageLoad();

interface AnimationEntry extends AnimationConfig {
  target:    TargetInput;
  position?: number | string;
}

Motion("hero", [
  // Title and image start at the same time (parallel)
  { target: ".title", from: { opacity: 0, y: 40 }, duration: 0.8, ease: "power3.out" },
  { target: ".image", from: { opacity: 0, scale: 0.9 }, duration: 0.8, ease: "power2.out", position: "<" },
  // Badge appears 0.3 s after both start
  { target: ".badge", from: { opacity: 0, scale: 0 }, duration: 0.4, ease: "back.out", position: "<0.3" },
  // Footer enters with a gap after everything else
  { target: ".footer", from: { opacity: 0 }, duration: 0.4, position: "+=0.2" },
]).onPageLoad();

tl.play(from?: number): this       // Play forward; optional start time in seconds
tl.pause(atTime?: number): this    // Pause; optional snap-to time
tl.reverse(from?: number): this    // Play backward; optional start time
tl.restart(): this                 // Seek to 0, restore initial CSS, play forward
tl.seek(position: number): this    // Jump to time without playing

tl.duration(): number
tl.progress(value?: number): number | this   // Normalized 0–1
tl.time(value?: number): number | this       // Current time in seconds
tl.timeScale(value?: number): number | this  // Speed multiplier (2 = double speed)
tl.isActive(): boolean                       // True while playing
tl.getName(): string | undefined             // Registered name

tl.call(callback: (...args: unknown[]) => void, params?: unknown[], position?: string | number): this

Motion("sequence", [
  { target: ".step-1", from: { opacity: 0 }, duration: 0.5 },
  { target: ".step-2", from: { opacity: 0 }, duration: 0.5 },
])
  .call(() => console.log("halfway"), [], 0.5)
  .call(() => console.log("done"))
  .onPageLoad();

tl.onStart(cb: () => void): this
tl.onUpdate(cb: (progress: number, time: number) => void): this
tl.onComplete(cb: () => void): this
tl.onRepeat(cb: (count: number) => void): this

tl.kill(clearProps?: boolean): void  // clearProps=true (default) restores initial CSS
tl.clear(): this                     // Reset and rebuild without destroying the instance

tl.withRepeat(config: number | RepeatConfig): this

// Infinite loop
Motion("pulse", ".dot", {
  from: { scale: 0.8, opacity: 0.6 },
  to:   { scale: 1.2, opacity: 1 },
  duration: 0.6,
}).withRepeat({ times: -1, yoyo: true }).onPageLoad();

// 3 times with yoyo + delay between cycles
Motion("bounce", [
  { target: ".box-a", to: { y: -40 }, duration: 0.4, ease: "power2.out" },
  { target: ".box-b", to: { y: -40 }, duration: 0.4, ease: "power2.out" },
]).withRepeat({ times: 3, yoyo: true, delay: 0.5 }).onPageLoad();

// ❌ Wrong — appends a second animation to the existing "hero" timeline
Motion("hero", "#hero", { from: { opacity: 0 }, duration: 0.8 }).onPageLoad();
// (somewhere later)
Motion("hero", "#hero", { from: { opacity: 0 }, duration: 0.8 }).onPageLoad();

// ✅ Correct — kill first, then rebuild from scratch
Motion("hero").kill();
Motion("hero", "#hero", { from: { opacity: 0 }, duration: 0.8 }).onPageLoad();

// Hide before page loads — no flash
Motion.set(".card", { opacity: 0, y: 30 });

// Reveal on scroll
Motion("cards", ".card", {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  stagger: 0.08,
}).onScroll({ scrub: false, toggleActions: "play none none none" });

const ctx = Motion.context(() => {
  Motion("hero", ".title", { from: { opacity: 0, y: 30 }, duration: 0.8 }).onPageLoad();
  Motion("cards", ".card", { from: { y: 100 }, duration: 1 }).onScroll({ scrub: true });
});

// After dynamic content change (AJAX filter, pagination, etc.)
ctx.refresh();   // kills old animations, re-runs init, re-resolves selectors

// Add more animations to the context later
ctx.add(() => {
  Motion("footer", ".footer-item", { from: { opacity: 0 }, duration: 0.4 }).onPageLoad();
});

// Full cleanup (React unmount, route change, etc.)
ctx.revert();

useEffect(() => {
  const ctx = Motion.context(() => {
    Motion("fade", ".box", { from: { opacity: 0 }, duration: 0.6 }).onScroll({ scrub: true });
  });
  return () => ctx.revert();
}, []);

let ctx: MotionContext | undefined;

document.addEventListener("astro:page-load", () => {
  ctx?.revert();
  ctx = Motion.context(() => {
    Motion("page-reveal", ".animate-in", { from: { opacity: 0, y: 20 }, duration: 0.5 }).onPageLoad();
  });
});

import { MotionUtils } from "@motion.page/sdk";

// toArray — convert selector to elements for manual iteration
const panels = Motion.utils.toArray(".panel");

// clamp — keep a value within bounds
const clamped = Motion.utils.clamp(0, 100, 150); // → 100

// Curried form — create a reusable clamp function
const clamp0to1 = Motion.utils.clamp(0, 1);
clamp0to1(1.5); // → 1

// mapRange — convert scroll progress to rotation
const progress = Motion.utils.mapRange(0, window.innerHeight, 0, 360, scrollY);

// interpolate — lerp between colors or numbers
const value = Motion.utils.interpolate(0, 100, 0.75); // → 75

// wrap — loop an index within a range
const index = Motion.utils.wrap(0, slides.length, currentIndex + 1);

// Group — hovering any card animates all of them
Motion("cards", ".card", { to: { y: -8 }, duration: 0.3 }).onHover({ onLeave: "reverse" });

// Independent — each card animates on its own hover
Motion("cards", ".card", { to: { y: -8 }, duration: 0.3 }).onHover({ each: true, onLeave: "reverse" });

Motion("list", ".item", {
  from: { opacity: 0, y: 20 },
  duration: 0.5,
  stagger: 0.08,
}).onPageLoad();
// Element 1 at 0s, element 2 at 0.08s, element 3 at 0.16s …

// Center-outward ripple on a grid
Motion("grid", ".cell", {
  from: { opacity: 0, scale: 0.6 },
  duration: 0.4,
  stagger: { each: 0.04, from: "center", grid: "auto" },
  ease: "power2.out",
}).onPageLoad();

// Shorthand number
repeat: 3     // 3 additional cycles after the first play
repeat: -1    // Infinite

// Full config object
interface RepeatConfig {
  times:  number;    // Additional repetitions; -1 = infinite
  delay?: number;    // Seconds between each repetition
  yoyo?:  boolean;  // Alternate direction each cycle
}

// Infinite yoyo
Motion("breathe", ".logo", {
  to: { scale: 1.08 },
  duration: 1.2,
  ease: "sine.inOut",
  repeat: { times: -1, yoyo: true },
}).onPageLoad();

// 3 times with yoyo + rest delay
Motion("shake", ".error-field", {
  from: { x: -6 },
  to:   { x:  6 },
  duration: 0.06,
  ease: "none",
  repeat: { times: 7, yoyo: true, delay: 0 },
}).play();

Motion("headline", "h1", {
  split: "words",
  from: { opacity: 0, y: "110%" },
  duration: 0.6,
  stagger: { each: 0.06, from: "start" },
  ease: "power3.out",
}).onPageLoad();

// Lines slide up from behind a clip — classic editorial reveal
Motion("reveal", ".tagline", {
  split: "lines",
  mask: true,
  from: { y: "100%" },
  duration: 0.7,
  stagger: 0.1,
  ease: "power3.out",
}).onPageLoad();

Motion("scramble", ".tagline", {
  split: "chars",
  flap: {
    type: "flip",
    charset: "alphanumeric",
    cycles: [2, 5],
  },
  from: { opacity: 0 },
  duration: 1.2,
  stagger: 0.04,
}).onPageLoad();

Motion("morph", ".source", {
  fit: { target: ".destination", resize: true },
  duration: 0.5,
  ease: "power2.inOut",
}).play();

// Draw a path from left to right
Motion("draw", "path.line", {
  from: { drawSVG: "0% 0%" },
  to:   { drawSVG: "0% 100%" },
  duration: 1.2,
  ease: "power2.inOut",
}).onScroll({ scrub: true });

// Circular reveal — expand from center
Motion("reveal", "#hero", {
  from: { 'clip-path': 'circle(0% at 50% 50%)' },
  to:   { 'clip-path': 'circle(75% at 50% 50%)' },
  duration: 1,
  ease: "power2.out",
}).onPageLoad();

// Diagonal wipe on hover
Motion("wipe", ".card-image", {
  from: { clipPath: 'polygon(0% 0%, 100% 0%, 100% 100%, 0% 100%)' },
  to:   { clipPath: 'polygon(0% 0%, 0% 0%, 100% 100%, 0% 100%)' },
  duration: 0.5,
  ease: "power2.inOut",
}).onHover({ onLeave: "reverse" });

// Inline in config
Motion("reveal", ".box", {
  from: { opacity: 0, y: 30 },
  duration: 0.6,
  onStart:           () => console.log("started"),
  onUpdate:          (progress) => console.log(`progress: ${progress.toFixed(2)}`),
  onComplete:        () => console.log("done"),
  onRepeat:          (count) => console.log(`repeat #${count}`),
  onReverseComplete: () => console.log("reversed"),
}).onPageLoad();

// Chained on the timeline
Motion("counter", "#count", {
  from: { opacity: 0 },
  duration: 0.4,
})
  .onStart(() => startTracking())
  .onUpdate((progress, time) => updateProgress(progress))
  .onComplete(() => finishTracking())
  .play();

// Create a context — all timelines created inside are tracked
const ctx = Motion.context(() => {
  Motion("hero", ".title", { from: { opacity: 0, y: 30 }, duration: 0.8 }).onPageLoad();
  Motion("cards", ".card", { from: { y: 100 }, duration: 1 }).onScroll({ scrub: true });
});

// After dynamic content change (filter, pagination, etc.)
ctx.refresh();  // kills old animations, re-runs init, re-resolves all selectors

// Add more animations to the same context
ctx.add(() => {
  Motion("new-section", ".new-item", { from: { opacity: 0 }, duration: 0.4 }).onPageLoad();
});

// Full cleanup — React unmount, route change, etc.
ctx.revert();

import type {
  // Core
  AnimationVars,
  AnimationConfig,
  AnimationEntry,
  TargetInput,
  ObjectTarget,
  AnimationTarget,
  EasingFunction,

  // Config options
  StaggerVars,
  RepeatConfig,
  SplitType,
  PathConfig,
  FitConfig,
  FlapConfig,

  // Trigger configs
  HoverConfig,
  ClickConfig,
  ScrollConfig,
  MouseMoveConfig,
  MarkerConfig,
  PageLoadConfig,
  PageExitConfig,

  // Gesture
  GestureConfig,
  GestureEvent,
  GestureAction,
  GestureInputType,
  TimelineAction,

  // Cursor
  CursorConfig,
  CursorStateVars,
  CursorSqueezeConfig,

  // Context
  MotionContext,
} from "@motion.page/sdk";

// Namespace import — all types under Types.*
import { Types } from "@motion.page/sdk";