SpringValue

Imperative APIs are a great way of animating in response to events, without the need for component state (ie: render-based updates). In this sense, the SpringValue class is a welcome addition to react-spring.

Create an animated value. Any type is valid, but only certain types are actually animated.

The props argument can be either..

• a to value
• or a set of useSpring props.

Types that cannot be animated are basically immediate: true animations. Such types include: a boolean, a display string like "none", etc.

The animatable types are:

• number

new SpringValue(0)

• string with numbers

new SpringValue('0px 10px')
new SpringValue('rgba(0, 0, 255, 1)')

• named colors

new SpringValue('red')

• and arrays of the preceding types

new SpringValue([0, '1em'])

Get the current value.

const value = spring.get()

Set the current value, replace the goal value, and stop animating.

spring.set(1)

Add an update to the queue array. All updates in the queue are applied at the same time.

const delays = [0, 100, 300]
for (const delay of delays) {
  spring.update({ x: delay })
}
spring.start()

⚠️ This method may be deprecated soon.

Process the queue array and replace it with an empty array.

The returned Promise resolves after every animation triggered by the queue array has either finished or been cancelled.

await spring.start()

The awaited value is an AnimationResult object.

Process the given props object.

The returned promise is resolved after the animation is finished or cancelled. If a start call triggers no animation, the promise resolves immediately.

await spring.start({ from: 0, to: 1 })

Process the given array of updates.

The returned promise resolves to an AnimationResult object whose:

• finished property is only true when every animation triggered by the queue was finished before being stopped or cancelled.

• cancelled property is only false when all updates in the queue were never cancelled.

// prettier-ignore
await spring.start([
  { from: 0 },
  { to: 10 },
  { to: 20, delay: 1000 },
])

Jump to the goal value immediately.

The onStart prop is called whenever finish is called before the first frame. The onRest prop is called with finished: true as expected.

spring.finish()

Jump to the given value immediately, and call the onStart and onRest props the same way .finish() does.

spring.finish(100)

Fluid values (eg: other SpringValue objects) can also be passed.

Stop animating and cancel any delayed updates.

The goal value is replaced with the current value.

spring.stop()

Restart the animation using its cached from and to values.

spring.reset()

Equivalent to a .start({ reset: true }) call.

Advance the current animation by the given dt (in milliseconds).

You will probably never call this.

// Advance a single frame.
spring.advance(1000 / 60)

Check for the given phase.

if (spring.is('PAUSED')) {
  return
}

Valid phases include:

• CREATED The spring has never animated since being created.
• IDLE The spring is done animating.
• ACTIVE The spring is animating.
• PAUSED The spring was animating but is now paused.
• DISPOSED The spring can no longer animate.

The name given to the SpringValue object by its owner.

For Controller objects, the key of each SpringValue is the property name from either the to or from object prop.

When defined, the to prop can be an object with this key defined as a property.

spring.key = 'foo'
spring.start({ to: { foo: '180deg' } })

Returns true when both:

• the current phase is anything but ACTIVE
• no async to prop is active

Put simply, it's true when not animating.

The end value of the current animation.

The velocity of the current animation.

The animation descriptor.

The queue of pending updates.

Call .start() to flush the queue.