Spring

A spring animation based on stiffness, damping and mass.

This simulation offers smoother motion and a greater variety of spring-feels than the basic spring simulation found in physics.

It’s based on the same equations underlying Apple’s CASpringAnimation.

Import

import { spring } from 'popmotion';

Usage

spring accepts a from and to value, and will output values to the function provided to start:

spring({ from: 0, to: 100 })
  .start(v => console.log(v))

Pass props like damping, stiffness and mass to affect the character of the spring:

spring({
  from: 0,
  to: 100,
  stiffness: 200,
  damping: 20
})

Value types

spring supports the animation of a number of different value types.

It’s generally best output as values that govern physical movement, like x, y and rotate, but it can be used to power colors and shadows.

Number

spring({ from: 0, to: 100 })

Units

Supported: px, %, deg, vh, and vw

spring({ from: '0px', to: '100px' })

Colors

Supported: RGB(A), HSL(A) and Hex

spring({ from: '#fff', to: '#000' })
spring({ from: 'rgba(0, 200, 100, 1)', to: 'rgba(60, 100, 80, 0.5)' })
spring({ from: 'hsl(0, 50%, 50%)', to: 'hsl(180, 80%, 50%)' })

Complex

Complex sequences of values, like SVG path definitions, CSS shadows and background gradients.

The non-numerical portions of these values must stay in the same format in the from and to props.

spring({
  from: '0px 0px 0px inset rgba(0, 0, 0, 0.2)',
  to: '3px 3px 10px inset rgba(0, 0, 0, 0.5)'
})
spring({
  from: 'linear-gradient(to right, #fff, #000)',
  to: 'linear-gradient(to right, #333, #666)'
})

Objects

Named objects composed of any of the above types may also be animated.

velocity, mass, damping and stiffness can also be set as objects, to apply property-specific settings:

spring({
  from: { x: '0px', y: '0px' },
  to: { x: '100px', y: '200px' },
  stiffness: { x: 200, y: 1000 },
  damping: { x: 10, y: 50 }
})

Arrays

Arrays composed of any of the above types may also be animated.

velocity, mass, damping and stiffness can also be set as arrays, to apply property-specific settings:

spring({
  from: ['10vh', 0],
  to: ['50vh', 100],
  stiffness: [400, 1000]
})

Props

The following properties may be passed to spring:

from

Start value of the animation.

Default: 0

to

End value of the animation.

Default: 1

stiffness

Stiffness of the spring. Higher values will create more sudden movement.

Default: 100

damping

Strength of opposing force. If set to 0, spring will oscillate indefinitely.

Default: 10

mass

Mass of the moving object. Higher values will result in more lethargic movement.

Default: 1

velocity

Initial velocity of the object, measured in units per second.

Default: 0

restDelta

End animation if distance to to is below this value and speed is below restSpeed. When animation ends, spring gets “snapped” to to.

Default: 0.01

restSpeed

End animation if absolute speed (in units per second) drops below this value and delta is smaller than restDelta.

Default: 0.01

Methods

Action methods

spring() returns:

start

Starts the animation and returns playback controls.

Can be provided either a function:

spring().start(v => {})

Or a named map of functions for update and complete:

spring().start({
  update: v => {},
  complete: () => {}
})

filter

Returns a new version of the animation, that filters out any value when the provided predicate function returns false:

const filtered = spring().filter(v => v > 0.5)

// This animation will only output values higher than 0.5:
filtered.start(v => {})

pipe

Returns a new animation that will pass any output value through this series of functions:

// This animation will round output values and then double them:
spring({ from: 0, to: 100 })
  .pipe(Math.round, v => v * 2)
  .start(v => {})

while

Returns a new animation that will complete when the provided predicate function returns false:

// This animation will end when an output value is higher than 0.5:
spring().while(v => v < 0.5)

Playback methods

spring().start() starts a new animation and returns the following playback methods:

stop

Stops the animation.

Example