New Personal Mail

    TypeScript icon, indicating that this package has built-in type declarations

    3.0.1 • Public • Published

    humpf logo

    📐 Humpf Build Status codecov

    Damped Spring position as a function of time

    What is this

    This a library that let you animate using a Damped Springs. The awesome thing about springs is that they can model all king of motions:

    • From A to B with a rebound at the end
    • From A to B smoothly
    • Decay (like pushing something)

    Difference with other libraries

    Most library out there will model spring by updating a value: on each frame they compute the forces applyed on the value and upate it accordingly. Humpf is different because it does not update a value but give you a function that take the time as parameter and return the position and velocity (speed) at that position in time.


    import { Spring } from 'humpf';
    const spring = Spring();
    spring(0); // { pos: 0, vel: 0 }
    spring(100); //  { pos: 26.4241, vel: 36.7879  }
    spring(200); //  { pos: 59.3994, vel: 27.0670 }
    spring(300); //  { pos: 80.0851, vel: 14.9361 }
    spring(500); //  { pos: 95.9572, vel: 3.3689 }
    spring(1000); //  { pos: 99.95006, vel: 0.0453 }
    spring(10000); //  { pos: 100, vel: 0 }


    You can pass different options to the spring to change it's behavior:

    // all the options (see below for more details)
      position: 0, // initial velocity
      equilibrium: 100, // position to approach (aka "to")
      velocity: 0, // initial velocity
      angularFrequency: 1, // how fast does it move ?
      dampingRatio: 1, // how much is it slowed down ?
      timeStart: 0, // time at which the annimation should start
      timeScale: 1 / 100, // [ADVANCED] change time scale

    position (default 0)

    This is the initiale position of the spring: the value when it starts (at timeStart).

    equilibrium (default 100)

    The equilibrium position of the spring: the value it will reach over time. If your spring bounce it will occilate around this value.

    velocity (default 0)

    The initial velocity of the spring. 0 mean it's stationary.

    Example: If your spring goes from 0 to 100, a positive velocity mean it's already going up so it will go faster. A negative velocity means it's going in the oposite direction and will go down a little before going up.

    angularFrequency (default 0)

    The angular frequency of your spring define how fast it wants to move. If you have a very bouncy spring (not much friction), the angular frequency define how many back and forth will happen.

    Example: 10 mean a lot of back and forth, so your spring will move fast. 0.5 is much lower so your spring will be slower

    dampingRatio (default 1)

    The damping ratio define how much resistance (friction) is opposed to your spring.
    If the damping ratio is less than 1 your spring will overshoot and bounce. If it's under 1 it will not.
    If the damping ratio is 1 it will reach the equilibrium as fast as possible without bouncing.

    timeStart (default 0)

    The time at which the spring should start.
    Usually you want to pass the current time to start a spring "now".

    Note: spring does not work in reverse, so you you try to get a value for a time before timeStart it will return the initial state.

    timeScale (default 1 / 100)

    The timeScale allow you to change how time is interpreted. The default value 1/100 will make your spring to take about a second to reach equilibrium. You probably don't need to change this.

    Math equations

    Most of the maths come from


    npm i humpf

    DownloadsWeekly Downloads






    Unpacked Size

    16.5 kB

    Total Files


    Last publish


    • etienne-dldc