arara arara logo
GitHub repository

Spring Animations

Spring animations provide a natural, physics-based way to animate values. They’re perfect for creating smooth, organic motion that responds to changing targets.

  • 🐦️ Physics-based spring motion
  • 🐦️ Configurable stiffness and damping
  • 🐦️ Automatic settling detection
  • 🐦️ Real-time target updates

Basic Usage Section titled Basic Usage

The simplest way to create a spring animation is using createSpring:

import { createSpring } from 'ararajs'

function SpringExample() {
const [spring, controller] = createSpring({
  target: 100,    // The value we're animating towards
  stiffness: 0.5, // How "rigid" the spring is
  damping: 0.5    // How quickly oscillations settle
})

return (
  <div style={{
    transform: `translateX(${spring.position}px)`
  }}>
    🔵
  </div>
)
}

Spring Configuration Section titled Spring Configuration

Springs can be customized through several parameters:

type SpringOptions = {
  mass: number         // Mass of the object (default: 1)
  target: number       // Target value to animate to
  damping: number      // Damping force (default: 0.5)
  stiffness: number   // Spring stiffness (default: 0.5)
  targetThreshold?: number  // Distance to target to consider "settled" (default: 0.001)
}

Understanding Spring Parameters Section titled Understanding Spring Parameters

  1. Mass - Higher mass means more inertia and slower response to forces
  2. Damping - Higher damping means less oscillation but slower settling
  3. Stiffness - Higher stiffness means faster motion but more oscillation
  4. Target Threshold - How close to the target we need to be to stop the animation

Example: Spring 2D with Mouse Section titled Example: Spring 2D with Mouse

Move Mouse

Advanced: Using Spring Pass Section titled Advanced: Using Spring Pass

For more complex animations, you can use the spring pass directly with createBodyAnimation:

import { springPass, type SpringOptions } from 'ararajs'

function ComplexSpringAnimation() {
// Create a spring with multiple passes
const [spring] = createBodyAnimation(
  () => [
    // Spring physics
    springPass({ 
      target: 100,
      stiffness: 0.5 
    }),
    // Additional passes (e.g., constraints)
    ({ body }) => ({
      ...body,
      position: Math.max(0, Math.min(100, body.position)) // Clamp position
    })
  ]
)

return (
  <div style={{
    transform: `translateX(${spring.position}px)`
  }}>
    🔵
  </div>
)
}