API

Physics

Simulate velocity, acceleration, friction and springs.

This is an integrated simulation, meaning the latest state is incorporated at discrete time intervals. It exposes set methods that change the simulation while it’s running.

This is unlike the differential equations in decay and spring, which can’t be changed while in motion (although both offer higher-accuracy simulations which lead to smoother animations).

Import

import { physics } from 'popmotion';

Usage

We can simulate a consistent velocity by providing the velocity property. Values are output to the function provided to start:

physics({ from: 0, velocity: 1000 })
  .start(v => console.log(v))

To slow the velocity down over time, we can provide a friction value between 0 (no friction) and 1 (dead stop):

physics({
  from: 0,
  velocity: 1000,
  friction: 0.8
})

To put speed back in the system we can use acceleration, measured in units per second:

physics({
  from: 0,
  velocity: 1000,
  acceleration: 200
})

To simulate a spring, we add to and springStrength values:

physics({
  from: 0,
  velocity: 1000,
  friction: 0.8,
  to: 400,
  springStrength: 500
})

Value types

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

Number

physics({ from: 0, velocity: 100 })

Units

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

physics({ from: '0px', velocity: 100 })

Objects

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

friction, acceleration, velocity and springStrength can also be set as objects, to apply property-specific settings:

physics({
  from: { x: '0px', y: '0px' },
  velocity: { x: 200, y: 1000 }
})

Arrays

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

friction, acceleration, velocity and springStrength can also be set as arrays, to apply property-specific settings:

physics({
  from: ['10vh', 0],
  velocity: [100, 100]
})

Props

The following properties may be passed to physics:

velocity

Velocity in units per second.

Default: 0

from

Start simulation from this number.

Default: 0

acceleration

Increase velocity by this amount every second.

Default: 0

restSpeed

When absolute speed drops below this value, complete is fired.

Default: 0.001

friction

Amount of friction to apply per frame, from 0 to 1.

Default: 0

springStrength

If set with to, will spring towards target with this strength.

Default: 0

to

If set with springStrength, will gradually “spring” towards this value.

Default: 0

Methods

Action methods

physics() returns:

start

Starts the animation and returns playback controls.

Can be provided either a function:

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

Or a named map of functions for update and complete:

physics().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 = physics().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:
physics({ from: 0, velocity: 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:
physics().while(v => v < 0.5)

Playback methods

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

set

Change the current value.

setAcceleration

Set acceleration.

setFriction

Set friction.

setSpringStrength

Set springStrength.

setSpringTarget

Set to.

setVelocity

Set velocity.

stop

Stops the animation.

Example