@petit-kit/animate

A lightweight animation library with time-based lerp and spring controllers for scalar, array, and object values.

• Installation
• lerp
• spring
• curves

Installation

npm install @petit-kit/animate
# or
pnpm add @petit-kit/animate

lerp

Time-based exponential smoothing. Interpolates toward a target using a per-frame factor (0–1) that is converted to time-based interpolation.

Usage

import { lerp } from '@petit-kit/animate';

// Scalar
const opacity = lerp({ from: 0, to: 1, lerp: 0.2 });
opacity.setTarget(1);
opacity.next(); // advance by real time (call each frame)

// Array
const position = lerp({ from: [0, 0], to: [1, 1], lerp: 0.15 });
position.setTarget([2, 3]);

// Object
const point = lerp({ from: { x: 0, y: 0 }, to: { x: 1, y: 1 } });
point.setTarget({ x: 2, y: 3 });

Options

| Option | Type | Default | Description | | ---------------- | --------- | ------- | --------------------------------------------- | | from | T | 0 | Initial value | | to | T | 1 | Initial target | | lerp | number | 0.1 | Interpolation intensity (0–1) per 60fps frame | | tolerance | number | 0.001 | Distance threshold to consider "at rest" | | resumeOnTarget | boolean | true | Resume when a new target is set after done |

API

| Method | Description | | ------------------------------- | --------------------------------------------------------------------------------- | | setTarget(nextTarget) | Set the target value. Resumes if done and resumeOnTarget is true | | setValue(nextValue, options?) | Set current value. Options: resetTime, setTarget, markDone | | getValue() | Get current value (cloned) | | isDone() | Whether the animation is at rest | | onResume(handler) | Subscribe to resume events. Returns unsubscribe | | step(dt) | Advance by dt seconds. Returns current value | | next(now?) | Advance by real elapsed time since last call. Uses performance.now() by default |

Game loop example

const pos = lerp({ from: [0, 0], to: [100, 100], lerp: 0.1 });

function tick() {
  const [x, y] = pos.next();
  element.style.transform = `translate(${x}px, ${y}px)`;
  requestAnimationFrame(tick);
}
tick();

spring

Time-based spring physics. Uses mass, stiffness, and damping to animate toward a target with natural overshoot and settle.

Usage

import { spring } from '@petit-kit/animate';

// Scalar
const scale = spring({ from: 0.8, to: 1, stiffness: 200, damping: 18 });
scale.setTarget(1.2);

// Array
const position = spring({ from: [0, 0], to: [1, 1], stiffness: 160 });
position.setTarget([2, 3]);

// Object
const point = spring({ from: { x: 0, y: 0 }, to: { x: 1, y: 1 } });
point.setTarget({ x: 2, y: 3 });

Options

| Option | Type | Default | Description | | ---------------- | --------- | ------- | --------------------------------------------------------- | | from | T | 0 | Initial value | | to | T | 1 | Initial target | | mass | number | 1 | Mass of the spring | | stiffness | number | 120 | Spring stiffness (k) | | damping | number | 14 | Damping coefficient (c) | | velocity | T | 0 | Initial velocity | | tolerance | number | 0.001 | Velocity and displacement threshold to consider "at rest" | | resumeOnTarget | boolean | true | Resume when a new target is set after done |

API

| Method | Description | | ------------------------------- | --------------------------------------------------------------------------------- | | setTarget(nextTarget) | Set the target value. Resumes if done and resumeOnTarget is true | | setValue(nextValue, options?) | Set current value. Options: resetVelocity, resetTime, setTarget, markDone | | getValue() | Get current value (cloned) | | isDone() | Whether the spring is at rest | | onResume(handler) | Subscribe to resume events. Returns unsubscribe | | step(dt) | Advance physics by dt seconds. Returns current value | | next(now?) | Advance by real elapsed time since last call. Uses performance.now() by default |

Game loop example

const scale = spring({ from: 0.8, to: 1, stiffness: 200, damping: 18 });

function tick() {
  const s = scale.next();
  element.style.transform = `scale(${s})`;
  requestAnimationFrame(tick);
}
tick();

curves

Easing functions for t in [0, 1]. Use with keyframe or timeline-based animations.

import { curves } from '@petit-kit/animate';

curves.linear(t);
curves.easeInQuad(t);
curves.easeOutQuad(t);
curves.easeInOutQuad(t);
curves.easeInCubic(t);
curves.easeOutCubic(t);
curves.easeInOutCubic(t);
// ... easeIn/Out/InOut for Quart, Quint, Expo, Circ, Back, Elastic, Bounce
curves.easeInSine(t);
curves.easeOutSine(t);
curves.easeInOutSine(t);