\n\n---\n\n## Why react-voodoo?\n\nMost animation libraries output **absolute values** — they own a CSS property and write a number to it each frame. That works fine for isolated transitions, but breaks down the moment you need to combine sources: a scroll position driving `translateY`, a drag gesture adding to the same `translateY`, and a parallax offset stacking on top. The libraries fight each other and you end up writing glue code.\n\nReact-voodoo takes a different approach: its engine computes **deltas** — the *change* from the previous frame — and accumulates them additively across any number of axes. Multiple animations on the same property simply add together. No ownership, no conflicts.\n\nThe engine is built on [tween-axis](../tween-axis/README.md) and uses its WebAssembly backend for hot-path property accumulation with zero JS-boundary crossings per frame.\n\nThis unlocks a set of features that are unique to the delta model:\n\n| Feature | How |\n|---|---|\n| **Additive multi-axis composition** | Each axis contributes a delta; they stack without coordination code. |\n| **Swipeable / draggable animations** | Drag gestures are mapped directly to axis positions with realistic momentum. |\n| **Predictive inertia** | The engine computes the final snap target *at the moment of release*, before the animation plays out — useful for preloading the next slide. |\n| **Physical spring settle** | `settle: { stiffness, damping, mass }` — the landing curve is generated at release from the actual gesture velocity (closed-form, no per-frame integration), with per-waypoint overrides. |\n| **Reduced-motion aware** | `reducedMotion: \"user\"` honors the OS *prefers-reduced-motion* setting: transitions jump to their predicted target, callbacks still fire, 1:1 dragging untouched. |\n| **SSR with correct initial styles** | Axes have a `defaultPosition`; styles are computed server-side and rendered inline — no flash on first paint. |\n| **DOM writes bypass React** | Style updates go straight to `node.style` via direct DOM writes, never triggering a re-render. |\n| **Multi-unit CSS via `calc()`** | Mix `%`, `px`, `vw`, `bw`/`bh` (box-relative units) in a single value — compiled to `calc()` automatically. |\n\n---\n\n## Comparison\n\n### Feature matrix\n\n| | **react-voodoo** | Framer Motion v12 | GSAP + ScrollTrigger | react-spring v10 | Motion v5 | anime.js v4 |\n|---|:---:|:---:|:---:|:---:|:---:|:---:|\n| Scroll-linked animation | ✅ | ✅ `useScroll` | ✅ | ⚠️ manual | ✅ | ✅ `ScrollObserver` |\n| Drag-linked animation | ✅ native | ✅ `drag` | ⚠️ manual | ✅ `@use-gesture` | ✅ gestures | ✅ `Draggable` |\n| **Additive multi-axis composition** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Physics / momentum inertia | ✅ predictive + springs | ✅ spring | ❌ | ✅ spring | ⚠️ limited | ✅ spring |\n| Reduced-motion (a11y) | ✅ built-in | ✅ built-in | ⚠️ manual | ✅ built-in | ✅ built-in | ⚠️ manual |\n| **Predictive snap target** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| **SSR — correct initial styles** | ✅ | ⚠️ flash | ⚠️ flash | ⚠️ flash | ⚠️ flash | ❌ |\n| Bypasses React render loop | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |\n| Transform layer composition | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| SVG geometry attributes | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |\n| Multitouch (drag multiple axes) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Bundle size (approx. gzip) | ~18 kB | ~32 kB | ~35 kB | ~25 kB | ~4 kB | ~10 kB |\n| React dependency | 16 – 19 | ≥ 18 | none | ≥ 16 | none | none |\n\n---\n\n## Performance\n\nThe delta model isn't just an architectural choice — the numbers back it up.\nIn the scenarios that define react-voodoo's use-case — **compositing multiple animation\nsources on the same element** — the engine runs **3–7× faster than GSAP** and handles\nfar more properties per frame without degrading.\n\n
\n \n
\n\n\nWhat each scenario measures\n\n| Scenario | Description |\n|---|---|\n| **sequential · 5 props** | Frame-by-frame advance, 5 CSS properties — the baseline everyone tests |\n| **property scale · 20 props** | Same advance with 20 properties — reveals engine scaling cost per property |\n| **additive ×3** | Three independent animation axes all writing to the same 5 properties simultaneously. This is react-voodoo's **native model**. Competitors must run 3 separate timelines and manually sum results. |\n| **spring layers** | Same 3 axes at different speeds (×1, ×0.7, ×0.3) — the signature scroll + drag + push composition pattern react-voodoo is built for |\n| **long timeline · 20 segs** | A timeline with 20 sequential animation segments — models a full-page scroll sequence or complex keyframe chain |\n\n\n\n\nWhy voodoo wins at scale\n\n- **Compiled-per-property processors** — at mount time each tween compiles a dedicated function (via `new Function`) that contains only the branches it needs. There is no per-property dispatch loop at runtime; property count scales at near O(1).\n- **WASM state machine** — the marker-scan loop (the part that decides which tweens are active as the cursor moves) runs entirely in WebAssembly. Zero JS-boundary crossings per frame in the hot path.\n- **Additive is free** — `goTo(pos, scope)` accumulates deltas into the same plain object regardless of how many axes call it. Competitors must maintain N separate target objects and merge them manually.\n\nThe one scenario where a stateless interpolator (Framer Motion / Popmotion) wins is\na **single small axis with easing**: pure math functions with no timeline state beat even\nWASM for trivially short timelines. That overhead is the fair cost of additive composability —\nand it disappears entirely once you have more than one axis compositing on the same element.\n\n\n\n> Full benchmark source: [`perf-compare/bench.js`](../perf-compare/bench.js)\n> Detailed analysis: [`doc/Alternatives libs perf comparaison.md`](doc/Alternatives%20libs%20perf%20comparaison.md)\n\n---\n\n## Installation\n\n```bash\nnpm install react-voodoo\n```\n\n**Peer dependencies:** `react` & `react-dom` 16 – 19\n\n---\n\n## All-in-one example\n\nEvery major feature in a single component, with comments explaining each part.\n\n```jsx harmony\nimport React from \"react\";\nimport Voodoo from \"react-voodoo\";\nimport {itemTweenAxis, tweenArrayWithTargets} from \"./somewhere\";\n\nconst styleSample = {\n\t/**\n\t * Voodoo.Node style property and the tween descriptors use classic CSS-in-JS declaration\n\t * exept we can specify values using the \"box\" unit which is a [0-1] ratio of the parent ViewBox height / width\n\t */\n\n\theight: \"50%\",\n\n\t// the tweener deal with multiple units\n\t// it will use css calc fn to add them if there's more than 1 unit used\n\twidth: [\"50%\", \"10vw\", \"-50px\", \".2box\"],\n\n\t// transform can use multiple \"layers\"\n\ttransform: [\n\t\t{\n\t\t\t// use rotate(X|Y|Z) & translate(X|Y|Z)\n\t\t\trotateX: \"25deg\"\n\t\t},\n\t\t{\n\t\t\ttranslateZ: \"-.2box\"\n\t\t}\n\t],\n\n\tfilter:\n\t\t{\n\t\t\tblur: \"5px\"\n\t\t}\n};\nconst axisSample = [// Examples of tween descriptors\n\t{\n\t\ttarget : \"someTweenRefId\", // target Voodoo.Node id ( optional if used as parameter on a Voodoo.Node as it will target it )\n\t\tfrom : 0, // tween start position\n\t\tduration: 100, // tween duration\n\t\teaseFn : \"easeCircleIn\", // function or easing fn id from [d3-ease](https://github.com/d3/d3-ease)\n\n\t\tapply: {// relative css values to be applied\n\t\t\t// Same syntax as the styles\n\t\t\ttransform: [{}, {\n\t\t\t\ttranslateZ: \"-.2box\"\n\t\t\t}]\n\t\t}\n\t},\n\t{\n\t\tfrom : 40,\n\t\tduration: 20,\n\n\t\t// triggered when axis has scrolled in the Event period\n\t\t// delta : a float value between [-1,1] is the update inside the Event period\n\t\tentering: ( delta ) => false,\n\n\t\t// triggered when axis has scrolled in the Event period\n\t\t// newPos, precPos : float values between [0,1] position inside the Event period\n\t\t// delta : a float value between [-1,1] is the update inside the Event period\n\t\tmoving: ( newPos, precPos, delta ) => false,\n\n\t\t// triggered when axis has scrolled out the Event period\n\t\t// delta : a float value between [-1,1] is the update inside the Event period\n\t\tleaving: ( delta ) => false\n\t}\n];\n\nconst Sample = ( {} ) => {\n\n\t/**\n\t * Voodoo tweener instanciation\n\t */\n\t\t// Classic minimal method\n\tconst [tweener, ViewBox] = Voodoo.hook();\n\t// get the first tweener in parents\n\tconst [parentTweener] = Voodoo.hook(true);\n\t// Create a tweener with options\n\tconst [twenerWithNameAndOptions, ViewBox2] = Voodoo.hook(\n\t\t{\n\t\t\t// Give an id to this tweener so we can access it's axes in the childs components\n\t\t\tname: \"root\",\n\t\t\t// max click tm in ms before a click become a drag\n\t\t\tmaxClickTm: 200,\n\t\t\t// max drag offset in px before a click become a drag\n\t\t\tmaxClickOffset: 100,\n\t\t\t// lock to only 1 drag direction\n\t\t\tdragDirectionLock: false,\n\t\t\t// allow dragging with mouse\n\t\t\tenableMouseDrag: false,\n\t\t\t// honor the OS prefers-reduced-motion setting : \"user\" | \"always\" | \"never\" (default)\n\t\t\t// when active : eased scrolls & anims jump to their final state, inertia\n\t\t\t// teleports to the predicted snap target ( callbacks still fire )\n\t\t\treducedMotion: \"user\"\n\t\t}\n\t);\n\t// get a named parent tweener\n\tconst [nammedParentTweener] = Voodoo.hook(\"root\")\n\n\t/**\n\t * once first render done, axes expose the following values & functions :\n\t */\n\t// Theirs actual position in :\n\t// tweener.axes.(axisId).scrollPos\n\n\t// The \"scrollTo\" function allowing to manually move the axes positions :\n\t// tweener.axes.(axisId).scrollTo(targetPos, duration, easeFn)\n\t// tweener.scrollTo(targetPos, duration, axisId, easeFn)\n\n\t// They can also be watched using the \"watchAxis\" function;\n\t// When called, the returned function will disable the listener if executed :\n\tReact.useEffect(\n\t\te => tweener?.watchAxis(\"scrollY\", ( pos ) => doSomething()),\n\t\t[tweener]\n\t)\n\n\treturn \n\t\t (currentPos > 500 ? -500 : null),\n\n\t\t\t\t\t// called when inertia know where it will end ( when the user stop dragging )\n\t\t\t\t\twillEnd: ( targetPos, targetDelta, duration ) => {\n\t\t\t\t\t},\n\n\t\t\t\t\t// called when inertia know where it will snap ( when the user stop dragging )\n\t\t\t\t\twillSnap: ( currentSnapIndex, targetWayPointObj ) => {\n\t\t\t\t\t},\n\n\t\t\t\t\t// called when inertia end\n\t\t\t\t\tonStop: ( pos, targetWayPointObj ) => {\n\t\t\t\t\t},\n\n\t\t\t\t\t// called when inertia end on a snap\n\t\t\t\t\tonSnap: ( snapIndex, targetWayPointObj ) => {\n\t\t\t\t\t},\n\n\t\t\t\t\t// settle easing : how the axis travels to the landing position\n\t\t\t\t\t// ( default : easePolyOut )\n\t\t\t\t\t// - any d3-ease fn name or custom easing fn\n\t\t\t\t\t// - or a physical spring : the curve is generated at release from\n\t\t\t\t\t// the actual gesture velocity ( velocity continuity + bounce ),\n\t\t\t\t\t// the predictive waypoint snap stays authoritative\n\t\t\t\t\tsettle: { stiffness: 200, damping: 14 },\n\n\t\t\t\t\t// list of waypoints ; gravity > 1 makes a waypoint stickier,\n\t\t\t\t\t// a per-waypoint settle overrides the axis-level one\n\t\t\t\t\twayPoints: [{ at: 100 }, { at: 200, gravity: 2, settle: \"easeCubicOut\" }]\n\t\t\t\t}\n\t\t\t}\n\t\t/>\n\n\t\t{/*\n\t\t * Voodoo.Node must have exactly ONE child element.\n\t\t * When you need multiple children, use Voodoo.Node.div — it renders\n\t\t * itself as the
container so its children are not Node's direct children.\n\t\t *\n\t\t * \n\t\t * child 1\n\t\t * child 2\n\t\t * \n\t\t */}\n\t\t {\n\t\t\t\t\t// start playing an anim ( prefer scrolling Axes )\n\t\t\t\t\ttweener.pushAnim(\n\t\t\t\t\t\t// make all tween target \"testItem\"\n\t\t\t\t\t\tVoodoo.tools.target(pushIn, \"testItem\")\n\t\t\t\t\t).then(\n\t\t\t\t\t\t( tweenAxis ) => {\n\t\t\t\t\t\t\t// doSomething next\n\t\t\t\t\t\t}\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t>\n\t\t\tmodify(delta)}\n\n\t\t\t\t// React ref to the box, default to the parent ViewBox\n\t\t\t\t// scale is as follow : (delta / ((xBoxRef||ViewBox).offsetWidth)) * ( axis.scrollableWindow || axis.duration )\n\t\t\t\t// xBoxRef={ref}\n\n\t\t\t\tyAxis={\"scrollY\"}// make drag y move the scrollY axis\n\t\t\t\t// yHook={(delta)=>modify(delta)}\n\t\t\t\t// yBoxRef={ref}\n\n\t\t\t\t// mouseDrag={true} // listen for mouse drag ( default to false )\n\t\t\t\t// touchDrag={false} // listen for touch drag ( default to true )\n\n\t\t\t\t// button={0-2} // limit mouse drag to the specified event.button ( default to 0; the left btn )\n\n\t\t\t\t// * actually Draggable create it's own div node\n\t\t\t>\n\t\t\t\t
\n\t\t\t\t\tSome content to tween\n\t\t\t\t
\n\t\t\t\n\t\t\n\t;\n}\n```\n\nFor a more complete annotated example with inertia callbacks, `watchAxis`, and programmatic scrolling, see the [full documentation](doc/readme.md).\n\n---\n\n## Core concepts in 30 seconds\n\n**Axis** — a virtual number line. Move its position (by drag, scroll, or code) and it drives CSS animations on any number of nodes.\n\n**Node** — a React element whose styles are controlled by one or more axes. Style updates go straight to `node.style`, no re-renders.\n\n**Delta composition** — each axis contributes a *change* per frame. Stack a horizontal drag axis and a parallax axis on the same `translateX` and they simply add together. No ownership, no conflicts.\n\n```\naxis position ──► tween engine ──► Δ per property ──► node.style (direct DOM write)\n ▲\n other axes add their Δ here\n```\n\n---\n\n## License\n\nReact-voodoo is dual-licensed:\n\n- **[CC BY-ND 4.0](http://creativecommons.org/licenses/by-nd/4.0)** — use freely in commercial projects; distribution of modified versions is not permitted.\n- **[AGPL v3](http://www.gnu.org/licenses/agpl-3.0)** — distribute modified versions under the same open-source license.\n\n---\n\n## Support the project\n\nIf react-voodoo saved you a day of work, consider supporting it:\n\n[](#)\n\n**BTC** — `bc1qh43j8jh6dr8v3f675jwqq3nqymtsj8pyq0kh5a`\n\n**PayPal** — \n","readmeFilename":"README.md"}
![](\"https://github.com/react-voodoo/react-voodoo/raw/master/doc/assets/logo-v0.png?sanitize=true\"){kind=logo}
![\"npm](\"https://img.shields.io/npm/v/react-voodoo.svg\")
\n![\"Build](\"https://travis-ci.org/react-voodoo/react-voodoo.svg?branch=master\")
\n![](\"https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat\"){kind=icon}
\n![\"License:](\"https://img.shields.io/badge/License-CC%20BY--ND%204.0-lightgrey.svg\"){kind=icon}
\n![\"License:](\"https://img.shields.io/badge/License-AGPL%20v3-blue.svg\"){kind=icon}
\n![](\"https://github.com/react-voodoo/react-voodoo/raw/master/doc/assets/demo.gif?sanitize=true\")
![\"Performance](\"./doc/assets/perf-chart.svg\")
\n![\"PayPal](\"https://img.shields.io/badge/paypal-donate-yellow.svg\"){kind=icon}
\n","readmeFilename":"README.md"}