Pmndrs.docs

Props

Overview

useSpring({ from: { ... }, to: { ... }, delay: 100, onRest: () => ... })

All primitives inherit the following properties (though some of them may bring their own additionally):

PropertyTypeDescription
fromobjBase values, optional
toobj/fn/array(obj)Animates to ...
loopobj/fn/boolLooping settings, see loop prop for more details
delaynumber/fnDelay in ms before the animation starts. Also valid as a function for individual keys: key => delay
immediatebool/fnPrevents animation if true. Also valid as a function for individual keys: key => immediate
configobj/fnSpring config (contains mass, tension, friction, etc). Also valid as a function for individual keys: key => config
resetboolThe spring starts to animate from scratch (from -> to) if set true
reversebool"from" and "to" are switched if set true, this will only make sense in combination with the "reset" flag
cancelbool/string/fnWhen true, the cancel prop stops the animation of every animated value owned by the Controller that receives it. See cancel prop for more details
pauseboolThe pause prop literally freezes animations in time.
eventsfnA variety of event callbacks (see events for more information)

Advanced Props

Loop Prop

Use loop: true to repeat an animation.

function LoopTrue() {
  const styles = useSpring({
    loop: true,
    from: { rotateZ: 0 },
    to: { rotateZ: 180 },
  })

  return (
    <animated.div
      style={{
        width: 80,
        height: 80,
        backgroundColor: '#46e891',
        borderRadius: 16,
        ...styles,
      }}
    />
  )
}

The loop function

Pass a function to be called after each loop. Return true to continue looping, or false to stop.

function LoopFunction() {
  const n = useRef(0)
  const styles = useSpring({
    loop: () => 3 > n.current++,
    from: { x: 0 },
    to: { x: 100 },
  })

  return (
    <animated.div
      style={{
        width: 80,
        height: 80,
        backgroundColor: '#46e891',
        borderRadius: 16,
        ...styles,
      }}
    />
  )
}

The loop function can also return a loop object, which is described in the next section. This is useful when you want to decide the next loop animation right after the previous loop is finished.

The loop object

Define a loop object to customize the loop animation separately from the initial animation. It may contain any of the useSpring props. For example, if reverse: true is used, the loop animation will reverse on each loop.

function LoopObject() {
  const styles = useSpring({
    loop: { reverse: true },
    from: { x: 0 },
    to: { x: 100 },
  })

  return (
    <animated.div
      style={{
        width: 80,
        height: 80,
        backgroundColor: '#46e891',
        borderRadius: 16,
        ...styles,
      }}
    />
  )
}

Inherited props

The loop object is always merged into a copy of the props object it was defined in. The following example shows a loop animation that inherits its config prop.

function InheritedProps() {
  const n = useRef(0)
  const styles = useSpring({
    from: { x: 0 },
    config: { duration: 1000 },
    loop: {
      x: 100,
    },
  })

  return (
    <animated.div
      style={{
        width: 80,
        height: 80,
        backgroundColor: '#46e891',
        borderRadius: 16,
        ...styles,
      }}
    />
  )
}

โš ๏ธ Notice how the loop doesn't run more than once. That's because some props are never inherited. These props include default, reset, and reverse.

To loop the animation, try adding reset: true to the loop prop in the above example. Alternatively, you could add from: { x: 0 } to get the same effect.

Lastly, try adding config: { friction: 5 } to the loop object. This overrides the inherited config.duration with a springy animation.

Cancel Prop

When true, the cancel prop stops the animation of every animated value owned by the Controller that receives it.

The following example never animates, because cancel is always true.

useSpring({
  cancel: true,
  from: { x: 0 },
  to: { x: 100 },
})

Once the cancel prop turns from true to false, the declared animation will resume or reset, depending on the given props.

Delayed updates

The cancel prop even prevents delayed updates. ๐Ÿ˜Ž

const [style, animate] = useSpring(() => ({ x: 0 }))

// Pass this to an element.
const onClick = () => {
  animate({ x: 100, delay: 500 })

  // Prevent the previous update. ๐Ÿคฃ
  animate({ cancel: true })
}

Specific keys

To cancel the animation of specific keys, you can pass a single key, an array of keys, or a (key: string) => boolean function.

// Using a single key
cancel: 'x',

// Using an array of keys
cancel: ['x', 'y'],

// Using a function
cancel: key => key !== 'x',

The reset and immediate props support these same types.

Events

Event nameDescription
onStartCallback when a spring or key is about to be animated
onChangeFrame by frame callback
onRestCallback when a spring or key comes to a stand-still
onPauseCallback when a spring or key is paused
onResumeCallback when a spring or key is resumed
onDelayEndCallback when a spring or key has finished being delayed
onPropsCallback when a spring or key's props have been updated

Events as functions

Events excluding onDelayEnd and onProps all have the same arguments passed to them:

(result: AnimationResult, spring: Controller | SpringValue, item?: Item) => void

So lets break this down:

  • result (1st arg) โ€“ is an Animation Result, this is an object containing the values of your spring at time of calling.
  • spring (2nd arg) โ€“ is either the Controller or SpringValue of the Animation Result, this called the event
  • item (3rd arg) โ€“ this is only available when using the useTransition hook or Transition component.

โš ๏ธ warning โš ๏ธ โ€“ Currently onStart is called after the first animation tick, this value is considered dirty

onDelayEnd & onProps have the following arguments passed:

(props: SpringProps, spring: SpringValue) => void
  • props (1st arg) โ€“ the props object of the spring (all merged from the new values just passed).
  • spring (2nd arg) โ€“ the affected SpringValue object

Events as objects

Events like can also be defined on a per-key basis.

useSpring({
  from: { x: 0, y: 0 },
  onRest: {
    x: () => console.log('x.onRest'),
    y: () => console.log('y.onRest'),
  },
})

Animation result

Some events receive an AnimationResult object as their first argument when called. It contains the following properties:

  • value: any The current value when the animation ended.
  • finished?: boolean Equals true when the animation finished before being stopped or cancelled.
  • cancelled?: boolean Equals true when the animation was cancelled.

The promise returned by the ref API's start method is resolved with an AnimationResult object, as well as the start method of the SpringValue and Controller classes.

Default props

The default prop lets you set the default value of certain props defined in the same update.

Declarative updates

For the declarative API, this prop is true by default. In the following example, the onRest handler is inherited by every update passed to animate, except when a call has its own onRest prop defined.

useSpring({
  to: async animate => { ... },
  onRest: () => { ... }
})

Imperative updates

Imperative updates can use default: true to set default props. When an async to prop is defined by an imperative update, it will inherit props from the imperative update like this:

useSpring({
  from: { x: 0 },
  to: async (animate) => {
    // The `config` prop below is inherited by
    // both objects in the `to` array.
    await animate({
      to: [{ x: 100 }, { x: 0 }],
      config: { tension: 100 },
    })
  },
})

Default props are inherited while an update is being processed by the internal diffing algorithm within the SpringValue#_merge method.

For example, both the ref prop and the animate function will inherit the default props defined below (in the useSpring props function).

const ref = useSpringRef()
const [{ x }, api] = useSpring(() => ({
  x: 0,
  onRest: () => { ... },
  ref,
}))

useEffect(async () => {
  // Animate to 100 with the ref API.
  await ref.current.start({ x: 100 })
  // Animate to 0 with the returned API.
  await api.start({ x: 0 })
}, [])

Compatible props

In the last example, only the onRest prop is inherited, because only some props can have a default value.

The following props can have default values:

  • cancel
  • config
  • immediate
  • onChange
  • onDelayEnd
  • onProps
  • onRest
  • onStart
  • pause

The default object

In addition to passing default: true, you can also pass an object instead. Only the props defined in your default object will be saved for future updates.

In this example, we are setting true as the default value of immediate. This affects all future animations owned by the useSpring call, whether or not they are declarative or imperative.

const { x } = useSpring({
  x: 0,
  default: { immediate: true },
})
useEffect(() => {
  // This will be immediate.
  x.start(100)
})