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