Props

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

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

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

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.

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

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.

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.

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

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

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.

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

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

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

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