spring

Get the next spring value using velocity and spring physics.

Usage

import { spring } from '@studiometa/js-toolkit/utils';

let currentValue = 0;
let currentVelocity = 0;
const targetValue = 100;

[currentValue, currentVelocity] = spring(
  targetValue,
  currentValue,
  currentVelocity,
  0.1, // stiffness
  0.6, // damping
  1, // mass
  0.01, // precision
);

console.log(currentValue, currentVelocity);

Parameters

• targetValue (number): The final value
• currentValue (number): The current value
• currentVelocity (number): The current velocity
• stiffness (number): The spring stiffness (or tension) factor, defaults to 0.1
• damping (number): The damping factor (or friction) to reduce oscillation, defaults to 0.6
• mass (number): The mass factor affecting acceleration, defaults to 1
• precision (number): The precision used to calculate the latest value, defaults to 1/1e4

Return value

• [number, number]: A tuple containing the next value and velocity

The function returns a tuple where:

• First element: The next position value
• Second element: The next velocity (set to 0 when the target is reached)

Physics explanation

The spring function simulates a spring-damper system where:

• Stiffness: Controls how quickly the spring tries to reach the target (higher = faster, more rigid)
• Damping: Reduces oscillation and controls energy loss (higher = less bouncy)
• Mass: Affects how the object responds to forces (higher = slower acceleration, more inertia)
• Precision: Determines when the spring is considered "at rest"

Types

function spring(
  targetValue: number,
  currentValue: number,
  currentVelocity: number,
  stiffness?: number,
  damping?: number,
  mass?: number,
  precision?: number,
): [number, number];

Examples

Animation loop

import { spring } from '@studiometa/js-toolkit/utils';

let position = 0;
let velocity = 0;
const target = 300;

function animate() {
  [position, velocity] = spring(target, position, velocity);

  element.style.transform = `translateX(${position}px)`;

  // Continue animating if not at target
  if (position !== target) {
    requestAnimationFrame(animate);
  }
}

animate();