v1.0.0

Magnetix.js

Magnetix is a lightweight, composable motion engine for the web. SVG path animation, magnetic interactions, timeline control, and rich text effects all unified under one clean API.

Get Started API Reference →

Setup

Installation

Import Magnetix directly via ES module. No build step required.

javascript

import Magnetix from "./src/index.js";
// Or destructure what you need
const { Easings, Timeline, svgMotion } = Magnetix;

Magnetix exports a single default object with all features. Every feature returns a motion object that integrates with the Timeline.

Foundations

Core Concepts

Three ideas power everything in Magnetix. Understand these and the rest clicks instantly.

Motion Objects

Every feature call returns a motion object. It doesn't run on its own — it's a description of what should happen.

Timeline Engine

The Timeline collects motion objects and orchestrates them. It controls play, pause, and seek across all animations simultaneously.

Composability

Any number of motions can be added to a timeline. They run in parallel and are controlled as one unit.

javascript — full pattern

// Step 1: Create motions (they don't run yet)
const m1 = Magnetix.svgMotion(".box", { ... });
const m2 = Magnetix.magnetic(".circle");

// Step 2: Add to timeline
const timeline = new Magnetix.Timeline();
timeline.add(m1, m2);

// Step 3: Control everything at once
timeline.play();
timeline.pause();
timeline.seek(0.5);  // jump to 50%

Feature

Magnetic

Attract elements toward the cursor with a configurable pull radius and spring physics. Great for buttons, icons, and interactive CTAs.

Hover me

javascript

const motion = Magnetix.magnetic(".circle", {
        strength: 0.5,
        radius: 100
});

Option	Type	Description
`selector`	string	CSS selector for the target element
`strength`	number	Pull force magnitude (default: 0.5)
`radius`	number	Mouse proximity threshold in px (default: 100)

Feature

SVG Motion

Animate any element along a complex bezier path. Define multi-segment cubic curves with per-segment easing and transforms.

javascript

const motion = Magnetix.svgMotion(".box", {
        duration: 12000,
        path: [
        { from: [0, 0], p1: [300, -200], p2: [600, 200], to: [300, 400] },
        { from: [300, 400], p1: [0, 600], p2: [-300, 200], to: [0, 0] },
        ],
        transform: {
        rotate: { value: 720, easing: Easings.easeInOutQuad },
        scale:  { value: 1.8, easing: Easings.easeInOutQuad },
        }
});

Option	Type	Description
`duration`	number	Total animation duration in ms
`path`	array	Array of bezier segments. Each has `from`, `p1`, `p2`, `to` as [x, y]
`transform.rotate`	object	`{ value, easing , unit }` — total rotation default(deg)
`transform.scale`	object	`{ value, easing }` — scale multiplier
`repeat`	number	Number of times the animation repeats (default: 0)
`yoyo`	boolean	Plays the animation forward and then in reverse on each repeat (default: false)

Feature

Split Text

Explode text into individual characters, words, or lines and animate each independently with staggered delays and custom transforms.

ENJOY MY LIBRARY

javascript

const motion = Magnetix.splitText(".title", "chars", {
        from: 0,
        to: 100,
        easing: Easings.easeInOutCubic, delay: 100,          // stagger delay between chars (ms)
        duration: 1200, transform: {
        scale: {
        value: 2,
        easing: Easings.easeOutBack
        },
        rotate: {
        value: 360,
        easing: Easings.easeInOutCubic
        }
        }
});

Option	Type	Description
`mode`	string	`"chars"` / `"words"` / `"lines"`
`delay`	number	Stagger delay between each unit in ms
`duration`	number	Duration per unit animation in ms
`transform`	object	Scale, rotate, translateY per character
`repeat`	number	Number of times the animation repeats (default: 0)
`yoyo`	boolean	Plays the animation forward and then in reverse on each repeat (default: false)

Feature

Morph

Smoothly transition between SVG path shapes. Ideal for blob backgrounds, logo transitions, and icon animations.

javascript

const motion = Magnetix.morph(".shape", {
        from: [
        { x: 20, y: 20 },
        { x: 80, y: 20 },
        { x: 50, y: 80 }
        ],
        to: [
        { x: 30, y: 10 },
        { x: 90, y: 50 },
        { x: 20, y: 90 }
        ],
        pointsCount: 3
});

Option	Type	Description
`from/to`	array	array of points
`delay`	number	Stagger delay between each unit in ms
`duration`	number	Duration per unit animation in ms
`pointsCount`	number	number of points used in the shape
`repeat`	number	Number of times the animation repeats (default: 0)
`yoyo`	boolean	Plays the animation forward and then in reverse on each repeat (default: false)

Feature

Cursor Follow

Attach a custom cursor element that follows the mouse with configurable lag, creating a silky trailing effect.

Move your cursor over this area

javascript

const motion = Magnetix.cursor(".cursor", {
        speed: 0.09    // lower = more lag (0.01 – 1.0)
});

Option	Type	Description
`speed`	number	Lerp factor per frame. Lower = more trailing. Range: 0.01 – 1.0

Feature

Drag

Make any element freely draggable with inertia. Elements snap naturally with momentum on release.

drag me

Try dragging the element

javascript

const motion = Magnetix.drag(".drag", {
        speed: 1
});

Feature

Parallax

Bind element movement to scroll position at different speeds, creating a depth illusion with multiple layers.

slow

mid

fast

javascript

import { parallax } from "./features/parallax/parallex.js";
parallax(".layer-1", { speed: 0.2 });   // slowest
parallax(".layer-2", { speed: 0.5 });   // mid
parallax(".layer-3", { speed: 0.9 });   // fastest

Feature

Reveal

Animate elements into view as they enter the viewport on scroll. Uses IntersectionObserver under the hood.

javascript

import reveal from "./features/reveal/reveal.js";

reveal(".section", {
        threshold: 0.2,      // % of element visible before trigger
        duration:  800,
        from: { opacity: 0, y: 40 },
        easing: Easings.easeOutCubic,
});

Option	Type	Description
`threshold`	number	0 – 1, how much of element must be visible
`duration`	number	Animation duration in ms
`from`	object	Starting CSS state: opacity, x, y, scale, rotate
`easing`	function	Any Easings function default(Linear)
`transform`	object	Controls element transformations: `scale`, `opacity`, `x`, `y`, `rotate`. Default units: `px` for position, `deg` for rotation.

Advanced

Timeline

The Timeline is your conductor. It collects all motions and gives you a single interface to play, pause, and scrub through everything simultaneously.

svgMotion

morph

splitText

Progress 0%

javascript — timeline composition

const timeline = new Magnetix.Timeline();
timeline.add(
    svgAnimation,   // svgMotion
    magneticAnimation,  // magnetic
    splitTextAnimation,  // splitText
    morphAnimation,  // morph
    cursorAnimation,  // cursor
    dragAnimation,  // drag
);

timeline.play();

// Seek to any point (0.0 → 1.0)
$$('seekBtn').addEventListener('click', () => timeline.seek(0.5));
$$('pauseBtn').addEventListener('click', () => timeline.pause());
$$('playBtn').addEventListener('click', () => timeline.play());

Advanced

Easings

A full library of easing functions for fine-tuning animation feel. Pass any easing as a function reference.

javascript

const { Easings } = Magnetix;
// Linear
Easings.linear
// Polynomial
Easings.easeInQuad      Easings.easeOutQuad      Easings.easeInOutQuad
Easings.easeInCubic     Easings.easeOutCubic     Easings.easeInOutCubic
Easings.easeInQuart     Easings.easeOutQuart     Easings.easeInOutQuart
// Special
Easings.easeInElastic   Easings.easeOutElastic   Easings.easeInOutElastic
Easings.easeInBack      Easings.easeOutBack      Easings.easeInOutBack
Easings.easeInBounce    Easings.easeOutBounce    Easings.easeInOutBounce

Reference

API Reference

Complete method signatures for every Magnetix feature.

MOTION svgMotion(selector, config)

Param	Type	Required	Description
`selector`	string	✓	CSS selector
`config.duration`	number	✓	ms
`config.path`	Segment[]	✓	Array of bezier segments
`config.transform`	object	—	`{ rotate, scale }`

MOTION splitText(selector, mode, config)

Param	Type	Required	Description
`selector`	string	✓	CSS selector
`mode`	string	✓	`"chars"` \| `"words"` \| `"lines"`
`config.duration`	number	✓	ms per unit
`config.delay`	number	—	stagger ms between units
`config.easing`	function	—	Easings.*
`config.transform`	object	—	scale, rotate, y offset

MOTION magnetic(selector, options?)

Param	Type	Required	Description
`selector`	string	✓	CSS selector
`options.strength`	number	—	Pull force 0.0–1.0
`options.radius`	number	—	Trigger radius in px

MOTION cursor(selector, options?)

Param	Type	Required	Description
`selector`	string	✓	CSS selector for cursor element
`options.speed`	number	—	Lerp factor 0.01–1.0

CLASS new Timeline()

Method	Signature	Description
`.add()`	add(...motions)	Register one or more motion objects
`.play()`	play() → void	Start or resume all motions
`.pause()`	pause() → void	Pause all motions
`.seek()`	seek(t: 0–1) → void	Jump to position in normalized time

Guide

Best Practices

Hard-won advice for building animations that feel professional.

⏱

Always use Timeline for multiple animations

Even if two motions could run independently, grouping them in a Timeline gives you unified pause/seek control — essential for interactive UIs and page transitions.

Keep durations consistent across a scene

When multiple animations have wildly different durations they feel disjointed. Anchor everything to a base duration and use multiples of it (×0.5, ×2) for hierarchy.

One easing family per scene

Pick a family (cubic, elastic, etc.) and stick to it. Mixing easeInOutCubic with easeOutBounce on adjacent elements creates visual noise, not delight.

Avoid stacking too many transforms

Combining rotate + scale + translate on the same element along an SVG path can conflict visually. Test each transform axis in isolation before combining.

Use seek() to build interactive scrubbers

The timeline.seek(t) method accepts a normalized 0–1 value, making it trivial to bind to a scroll position, slider, or progress bar for interactive storytelling.

Pause animations when off-screen

Use an IntersectionObserver to call timeline.pause() when the animated section leaves the viewport. This saves battery and CPU on long pages.