🪐 Vader Motion Engine

A lightweight, powerful motion library for VaderJS (or vanilla JS) inspired by Framer Motion and GSAP. Animate DOM elements and reactive states with ease: supports timelines, staggered motion, keyframes, spring physics, color interpolation, and more.

⚡ Features

• Reactive Motion State: useMotionState lets you bind motion values to JSX/CSS easily.
• Animate Anything: animate() works with transforms, colors, opacity, numbers.
• Timeline Sequencing: timeline() supports sequential, parallel, and staggered animations.
• Keyframes & Spring Physics: Support for natural, physics-like motion.
• Staggered Animations: Animate multiple elements with delays.
• Color Interpolation: Animate between rgb, rgba, or hex colors.
• Transforms Map: Full CSS transform support (translate, rotate, scale, skew, perspective).
• Global Animation Controls: Pause, resume, stop, or reverse animations easily.
• Declarative API: Designed for JSX/TSX but works with vanilla JS too.
• Lightweight: Small footprint, no dependencies.

📦 Installation

# For VaderJS projects
npm install vader-motion

Or copy vader-motion.ts into your project.

🛠 Usage

1. Basic Animate

import { animate } from "vader-motion";

const box = document.getElementById("box");

animate(box, {
  from: { opacity: 0, translateY: 50 },
  to: { opacity: 1, translateY: 0 },
  duration: 1,
  ease: "spring"
});

2. Timeline (Sequential & Staggered Animations)

import { timeline } from "vader-motion";

const tl = timeline();

tl.to(box, { opacity: 1, translateY: 0 }, { duration: 0.8 })
  .stagger([...buttons], { opacity: 1, translateY: 0 }, { duration: 0.6, stagger: 0.2 })
  .play();

• .to(): Animate to a value
• .fromTo(): Animate from one value to another
• .stagger(): Animate multiple elements with delays
• .play(), .pause(), .resume(), .stop()

3. Reactive Motion State (Hook)

import { useMotionState } from "vader-motion";

const [motion, setMotion] = useMotionState({ rx: 0, ry: 0, scale: 1 });

// Update reactive values
setMotion({ rx: 10, ry: -5, scale: 1.2 });

// Use in JSX or vanilla style updates
card.style.transform = `rotateX(${motion.rx}deg) rotateY(${motion.ry}deg) scale(${motion.scale})`;

• Animations are smooth and frame-based.
• Works with mouse movement, gestures, or programmatic changes.

4. Spring Physics Animation

animate(box, {
  from: { scale: 0 },
  to: { scale: 1 },
  ease: "spring",
  duration: 1.5
});

• ease: "spring" gives a natural bouncing effect.
• Optional springConfig for stiffness, damping, mass.

5. Color Interpolation

animate(box, {
  from: { backgroundColor: "#ff0000" },
  to: { backgroundColor: "#00ff00" },
  duration: 2
});

• Supports rgb(), rgba(), hex, and named CSS colors.

6. Staggered Animations Example

const buttons = document.querySelectorAll(".btn");
timeline()
  .stagger(buttons, { opacity: 1, translateY: 0 }, { from: { opacity: 0, translateY: 20 }, stagger: 0.15 })
  .play();

7. Full Transform Support

animate(box, {
  from: { translateX: 0, rotate: 0, scale: 1 },
  to: { translateX: 100, rotate: 360, scale: 1.5 },
  duration: 1.2
});

8. Global Controls

const anim = animate(box, { opacity: 0, duration: 1 });
anim.controls.pause();
anim.controls.resume();
anim.controls.reverse();
anim.controls.stop();

🎨 Example Hero Page

import { animate, timeline, useMotionState } from "vader-motion";
import { useRef, useEffect } from "vaderjs";

export default function Hero() {
  const cardRef = useRef(null);
  const [motion, setMotion] = useMotionState({ rx: 0, ry: 0, scale: 1 });

  useEffect(() => {
    const tl = timeline();
    if (cardRef.current) {
      tl.fromTo(cardRef.current, { scale: 0, opacity: 0 }, { scale: 1, opacity: 1, ease: "spring" }).play();
    }
  }, []);

  const handleMouseMove = (e) => {
    const r = cardRef.current.getBoundingClientRect();
    const rx = ((e.clientY - r.top - r.height / 2) / r.height) * -15;
    const ry = ((e.clientX - r.left - r.width / 2) / r.width) * 15;
    setMotion({ rx, ry });
    cardRef.current.style.transform = `perspective(1000px) rotateX(${motion.rx}deg) rotateY(${motion.ry}deg) scale(${motion.scale})`;
  };

  return <div onMouseMove={handleMouseMove} ref={cardRef}>Vader Hero Card</div>;
}

⚡ Tips & Best Practices

1. Always define from and to explicitly for consistent animation.
2. Use timeline() for multiple sequential or staggered animations.
3. Reactive motion state (useMotionState) is ideal for hover, drag, or mouse-based interactions.
4. Spring physics is better for natural, bouncy effects.
5. Color properties require a valid CSS color string.

📝 License

MIT — free to use and modify.