Pmndrs.docs

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.

Intro

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

The props argument can be either..

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'])

Methods

get(): T

Get the current value.

const value = spring.get()

set(value): this

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

spring.set(1)

update(props): this

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.

start(): Promise

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.

start(props): Promise

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 })

start(queue): Promise

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 },
])

finish(): this

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()

finish(value): this

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(): this

Stop animating and cancel any delayed updates.

The goal value is replaced with the current value.

spring.stop()

reset(): this

Restart the animation using its cached from and to values.

spring.reset()

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

advance(dt: number): boolean

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

You will probably never call this.

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

is(phase: string): void

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.

Properties

key?: string

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' } })

get idle(): boolean

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.

get goal(): T

The end value of the current animation.

get velocity(): number | number[]

The velocity of the current animation.

animation: Animation

The animation descriptor.

queue?: SpringUpdate<T>[]

The queue of pending updates.

Call .start() to flush the queue.