npm install humpf
# here is the copy/paste for yarn
yarn add humpf


Humpf has three main exports as well as a few types for TypeScript users:
(you can click on each to scroll to corresponding section)

import { Spring, SpringConfig, SpringSequence } from 'humpf';
// Types exports (for TypeScript users only)


Create a spring function using an optional config.
const spring = Spring();

This function returns a SpringFn function.

The Spring function accept an optional config parameter.

const spring = Spring({ equilibrium: 200 });

This config object must be of type SpringConfig (all properties are optional).


The SpringConfig type is used to create a Spring

The SpringConfig export is also a value (see below).

Here are all its properties as well as the default values.

const DEFAULT_CONFIG: SpringConfig = {
// initial position
position: 0,
// initial velocity
velocity: 0,
// position to approach
equilibrium: 100,
// angular frequency of motion
angularFrequency: 1,
// damping ratio of motion
dampingRatio: 1,
// [advanced] multiply time by this value
timeScale: 1 / 100,
// time at which the animation should start (after timeScale has been applied)
timeStart: 0,
// precision let you specify how to round values
// value are rounded to be able to check if velocity === 0 for example
positionPrecision: 0.00006103515625; // 1 / (1 << 14)
velocityPrecision: 0.00006103515625; // 1 / (1 << 14)
dampingRatioPrecision: 0.00006103515625; // 1 / (1 << 14)

To better understand the different options of the spring and how to use them take a look a the Article.


The SpringConfig namespace contains a few helper function to create and minipulate SpringConfig object.

The SpringConfig export is also a type, see above for the definition of that type.

export const SpringConfig = {
// presets
// special
// utils


Preset functions let you create pre defined SpringConfig object.

const spring = Spring(SpringConfig.basic());
// same as
// const spring = Spring({ angularFrequency: 1, dampingRatio: 1 });

You can also pass a SpringConfig object to any preset function to override any property.

const spring = Spring(SpringConfig.basic({ equilibrium: 200 }));


Decay take a SpringConfig and returns a new SpringConfig where the equilibrium is proportional to the velocity and the dampingRatio is 1

You can use this to animate the end of a "drag" motion, once the user lift its finger but the object has some velocity left.

Initial velocity: 50

const spring = Spring(SpringConfig.decay({ velocity: 50 }));

You can adjust the "force" of the decay by changing the angularFrequency

Initial velocity: 50

Angular Frenquency: 1

const spring = Spring(SpringConfig.decay({ velocity: 50 }));


The SpringConfig.stable function produce a spring that does not move.

const spring = Spring(SpringConfig.stable(200));
spring(time); // { pos: 200, vel: 0 }

To achieve this, the equilibrium and the position are set to the same value and the initial velocity is set to 0

const spring = Spring({ equilibrium: 200, position: 200, velocity: 0 });
spring(time); // { pos: 200, vel: 0 }


Take a velocity and an optional angularFrequency and return the decay equilibrium of a critically damped spring (dampingRatio = 1).

const equilibrium = SpringConfig.findEquilibrium(50, 2);


Take a mass and an optional springContant and return the corresponding angularFrequency.

const angularFrequency = SpringConfig.angularFrequencyFromMass(100, 1);


Take a springContant and an optional mass and return the corresponding angularFrequency.

const angularFrequency = SpringConfig.angularFrequencyFromMass(1, 100);


The SpringFn type is the function returned by the Spring function.
const spring = Spring();
// ^^^^^^ this has a type SpringFn

This function take only one parameter: the time (as a number) and return a SpringResult object.

type SpringFn = (t: number) => SpringResult;
const spring = Spring();
const time = 1000;
spring(time); // { position: 0.986, velocity: 0.011 }

The SpringFn type also has two functions to get the position and velocity only.

const spring = Spring();
const time = 1000;
spring.position(time); // 0.986
spring.velocity(time); // 0.011


This object is the result of calling a SpringFn

This object contains two property position and velocity, corresponding to the position and velocity of the spring motion.

interface SpringResult {
position: number;
velocity: number;

Here is a small example combining everything above:

import { Spring, SpringConfig } from "humpf";
const spring = Spring(SpringConfig.basic({ position: 0, equilibrium: 100 }));
spring(0); // { position: 0, velocity: 0 }
spring(200); // { position: 59, velocity: 27 }
spring(400); // { position: 90, velocity: 7 }
spring(600); // { position: 98, velocity: 1 }
spring(800); // { position: 100, velocity: 0 }


The SpringSequence is a higher order class that let you manipulate a sequence of Spring over time.

Documentation comming soon.


Since SpringSequence is a class, you can use SpringSequence as a type.
const seq: SpringSequence = SpringSequence.create();