withSpring
withSpring lets you create spring-based animations.
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".
- Hexadecimal integer - e.g.
- 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 matrix is decomposed into rotation, scale, skew, translation, and perspective, which are animated separately. Singular matrices, such as a transform with zero scale, use interpolation of individual matrix entries instead.
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.
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. |
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
Remarks
- The callback passed to the 3rd argument is automatically workletized and ran on the UI thread.
Platform compatibility
| Android | iOS | Web |
|---|---|---|
| ✅ | ✅ | ✅ |