withSpring

withSpring lets you create spring-based animations.

Loading...

Reference

import { withSpring } from 'react-native-reanimated';

function App() {
  sv.value = withSpring(0);
  // ...
}

Type definitions

type AnimatableValue = number | string | number[];

export type SpringConfig = {
  mass?: number;
  overshootClamping?: boolean;
  energyThreshold?: number;
  velocity?: number;
  reduceMotion?: ReduceMotion;
} & (
  | {
      stiffness?: number;
      damping?: number;
      duration?: never;
      dampingRatio?: never;
      clamp?: never;
    }
  | {
      stiffness?: never;
      damping?: never;
      duration?: number;
      dampingRatio?: number;
      clamp?: { min?: number; max?: number };
    }
);

function withSpring<T extends AnimatableValue>(
  toValue: T,
  config?: WithSpringConfig,
  callback?: (finished?: boolean, current?: AnimatableValue) => void
): T;

enum ReduceMotion {
  System = 'system',
  Always = 'always',
  Never = 'never',
}

Arguments

toValue

The value on which the animation will come at rest. Supported categories:

• numbers - number can be a either a number or a string
• suffixed numbers - strings being a number with a unit, like "5.5%", "90deg" or even "3bananas". Just make sure there is no space between number and suffix, also suffix should consist of basic english letters only.
• colors
  • Hexadecimal integer - e.g. 0xff1234,
  • RGB (Red, Green, Blue) - e.g. "rgb(100, 50, 0)",
  • RGBA (Red, Green, Blue, Alpha) - e.g. "rgba(255, 105, 180, 0)",
  • RGB Hexadecimal - e.g. "#53575E",
  • HSL (Hue, Saturation, Lightness) - e.g."hsl(0, 50%, 50%)",
  • Named colors - e.g. "dodgerblue".
• objects - object with properties that will be animated separately,
• array - array of numbers, each value will be animated separately.
• transformation matrix - an array consisting of exactly 16 numerical values is by default animated as a transformation matrix. The numbers in the matrix aren't animated separately. Instead, the array gets decomposed into 3 basic transformations - rotation, scale, and translation – which are then animated separately.

Please mind, that toValue and the animated shared value have to share the same category (e.g. you can't animate width from 100px to 50%).

config

Optional

The spring animation configuration.

Loading...

Available for physics-based spring:

Name	Type	Default	Description
damping Optional	number	120	How quickly a spring slows down. Higher damping means the spring will come to rest faster.
stiffness Optional	number	900	How bouncy the spring is.

Available for duration-based spring:

Name	Type	Default	Description
duration Optional	number	550	Perceptual duration of the animation in milliseconds. Actual duration is 1.5 times the value of perceptual duration.
dampingRatio Optional	number	1	How damped the spring is. Value 1 means the spring is critically damped, value >1 means the spring is overdamped and value <1 means the spring is underdamped.

info

The stiffness and damping (physics-based) properties can't be used at the same time as duration and dampingRatio (duration-based).

When used together duration and dampingRatio overrides stiffness and damping props.

Available for every spring animation:

Name	Type	Default	Description
mass Optional	number	4	The weight of the spring. Reducing this value makes the animation faster.
velocity Optional	number	0	Initial velocity applied to the spring equation.
overshootClamping Optional	boolean	false	Whether a spring can bounce over the toValue.
energyThreshold Optional	number	6e-9	Relative energy threshold below which the spring will snap without further oscillations.
reduceMotion Optional	ReduceMotion	ReduceMotion.System	A parameter that determines how the animation responds to the device's reduced motion accessibility setting.
clamp Optional	[number, number]	undefined	Limit of the scope of movement. If your spring would exceed this limit, then dampingRatio will be reduced (to make the spring less bouncy).

callback

Optional

A function called upon animation completion. If the animation is cancelled, the callback will receive false as the argument; otherwise, it will receive true.

Returns

withSpring returns an animation object which holds the current state of the animation. It can be either assigned directly to a shared value or can be used as a value for a style object returned from useAnimatedStyle.

Example

Loading...

Remarks

• The callback passed to the 3rd argument is automatically workletized and ran on the UI thread.

Platform compatibility

Android	iOS	Web
✅	✅	✅