Monomove

A minimal, high-performance, strictly typed animation and smooth scrolling library for the modern web.

---

Installation

npm install @monokai/monomove

Quick Start

Object Animation

Tween properties of an object.

import { tween } from '@monokai/monomove';

const box = { x: 0, opacity: 0 };

tween(box)
	.to({ x: 100, opacity: 1 }, 1.5)
	.easing('easeOutExpo') 
	.onUpdate((target) => {
		element.style.transform = `translateX(${target.x}px)`;
		element.style.opacity = target.opacity.toString();
	})
	.start();

Scalar Animation

Tween a single value from 0 to 1 (or custom range).

import { tween } from '@monokai/monomove';

tween(val => {
	element.style.opacity = val.toString();
}, 0.5)
	.from(0)
	.to(1)
	.start();

Easing Presets

To keep the core library small, easing presets are not included by default.

Option A: The "Magic" Import (Easiest) Import the presets side-effect file once in your app. This registers all standard CSS easings (easeIn, easeOutExpo, etc.) globally.

import '@monokai/monomove/easings';
import { tween } from '@monokai/monomove';

tween(obj).to({ x: 100 }).easing('easeOutBack').start();

Option B: Tree-Shakable (Smallest Bundle) Import only the specific curves you need to save bytes.

import { tween, TweenManager } from '@monokai/monomove';
import { BezierPresets } from '@monokai/monomove/easings';

TweenManager.register('bounce', BezierPresets.easeOutBack);

tween(obj).easing('bounce').start();

API Reference

tween(target, duration?)

The main factory function. Returns strictly typed IScalarTween or IObjectTween.

Methods:

Method	Arguments	Description
.to(props, duration?)	Partial	number, number
.from(props)	Partial	number
.duration(seconds)	number	Set duration in seconds.
.delay(seconds)	number	Wait before starting.
.easing(type)	string	Array
.loop(count)	number	Loop the animation n times (Infinity for endless).
.onUpdate(cb)	(obj, progress, delta) => void	Called every frame.
.onComplete(cb)	(obj) => void	Called when animation finishes.
.onStart(cb)	(obj) => void	Called when animation begins (after delay).
.start()	-	Starts the tween. Returns a Promise.
.stop()	-	Stops the tween immediately.

timeline(options?)

Sequence multiple tweens together.

import { timeline, tween } from '@monokai/monomove';

const tl = timeline({ delay: 0.5, onComplete: () => console.log('Done') });

tl.add(tween(obj).to({ x: 100 }, 1))
	.add(tween(obj).to({ y: 100 }, 1), -0.5) // Overlap by 0.5s
	.start();

Method	Description
.add(tween, offset?)	Add a tween. offset (seconds) shifts it relative to the previous tween's end.
.at(time, tween)	Insert a tween at an absolute timestamp.
.timeScale(scale)	Speed up (2), slow down (0.5), or reverse (-1) the timeline.
.loop(count)	Loop the entire sequence.
.setProgress(0-1)	Scrub the timeline manually.

SmoothScroller

A high-performance scroller that uses IntersectionObserver to trigger animations only when elements are in view. It does not hijack native scrolling (unless you build a custom smooth scroll container), making it accessibility-friendly.

import { SmoothScroller } from '@monokai/monomove';

const scroller = new SmoothScroller({
	scrollDuration: 0.5, // 0 = native
	listener: window
});

const elements = document.querySelectorAll('.card');

scroller.add(Array.from(elements), (data) => {
	const y = (1 - data.boxFactor) * 100; 

	data.item.style.transform = `translateY(${y}px)`;

	if (data.isInView) {
		data.item.style.opacity = '1';
	}
});

Callback Data Object

The callback receives a rich data object for math-based animations:

Property	Type	Description
item	HTMLElement	The DOM element.
scroll	number	Current scroll Y position.
factor	0 to 1	Viewport Progress: 0 = entering bottom, 1 = leaving top.
boxFactor	0 to 1	Box Progress: 0 = top of item at bottom of screen, 1 = bottom of item at top of screen.
isInView	boolean	Is the element currently visible?

Helper Utilities

animate(target, to, duration, easing)

A simple "fire-and-forget" wrapper.

import { animate } from '@monokai/monomove';

await animate(element.style, { opacity: 0 }, 0.5, 'linear');

element.remove();

delay(seconds)

Promise-based delay.

import { delay } from '@monokai/monomove';

await delay(1);

console.log('1 second passed');

RenderLoop

Hook into the library's single requestAnimationFrame loop.

import { RenderLoop } from '@monokai/monomove';

const stop = RenderLoop.add((deltaMS) => {
	// Custom logic running every frame
	return true; // return false to remove automatically
});

License MIT © Monokai