addimated

An always interruptable, declarative animation library for React.

Installation

# use npm
npm install @unstable/addimated

# use yarn
yarn add @unstable/addimated

Usage

import * as Animated from "@unstable/addimated";

Examples

• Spring/Timing Interruption
• With react-with-gesture

API Reference

Animated Values

createAnimatedValue(initialValue: number): AnimatedValue

Creates a standard value for driving animations.

createAnimatedValueXY(initialValueXY: { x: number, y: number }): AnimatedValueXY

Creates a 2D value for driving 2D animations, such as pan gestures.

Interpolation

interpolate(value: AnimatedValue, config: Object): AnimatedValue

Maps input ranges to output ranges, typically using a linear interpolation but also supports easing functions. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value.

Config is an object that may have the following options:

• inputRange: (required)
• outputRange: (required)
• easing:
• extrapolate:
• extrapolateLeft:
• extrapolateRight:

Animations

timing(value: AnimatedValue|AnimatedValueXY, config: Object): Animation

Animates a value along a timed easing curve. The Easing module has tons of predefined curves, or you can use your own function.

Config is an object that may have the following options:

• toValue: (required) Next value to animate to
• duration: Length of animation (milliseconds). Default 500.
• easing: Easing function to define curve. Default is Easing.inOut(Easing.ease).
• delay: Start the animation after delay (milliseconds). Default 0.

spring(value: AnimatedValue|AnimatedValueXY, config: Object): Animation

Animates a value according to an analytical spring model based on damped harmonic oscillation. Tracks velocity state to create fluid motions as the toValue updates, and can be chained together.

Config is an object that may have the following options.

Note that you can only define one of bounciness/speed, tension/friction, or stiffness/damping/mass, but not more than one:

The friction/tension or bounciness/speed options match the spring model in Facebook Pop, Rebound, and Origami.

• friction: Controls "bounciness"/overshoot. Default 7.
• tension: Controls speed. Default 40.
• speed: Controls speed of the animation. Default 12.
• bounciness: Controls bounciness. Default 8.

Specifying stiffness/damping/mass as parameters makes Animated.spring use an analytical spring model based on the motion equations of a damped harmonic oscillator. This behavior is slightly more precise and faithful to the physics behind spring dynamics, and closely mimics the implementation in iOS's CASpringAnimation primitive.

• stiffness: The spring stiffness coefficient. Default 100.
• damping: Defines how the spring’s motion should be damped due to the forces of friction. Default 10.
• mass: The mass of the object attached to the end of the spring. Default 1.

Other configuration options are as follows:

• toValue: (required) Next value to animate to
• velocity: The initial velocity of the object attached to the spring. Default 0 (object is at rest).
• overshootClamping: Boolean indicating whether the spring should be clamped and not bounce. Default false.
• restDisplacementThreshold: The threshold of displacement from rest below which the spring should be considered at rest. Default 0.001.
• restSpeedThreshold: The speed at which the spring should be considered at rest in pixels per second. Default 0.001.
• delay: Start the animation after delay (milliseconds). Default 0.

Composite Animations

delay(time: number): Animation

Starts an animation after the given delay

sequence(animations: Animation[]): Animation

Starts an array of animations in order, waiting for each to complete before starting the next. If the current running animation is stopped, no following animations will be started.

parallel(animations: Animation[]): Animation

Starts an array of animations all at the same time.

stagger(time: number, animations: Animation[]): Animation

Array of animations may run in parallel (overlap), but are started in sequence with successive delays. Nice for doing trailing effects.

Animated Components

createAnimatedComponent(component: React.Component|string): AnimatedComponent

Make any React component Animatable. Used to create Animated.div, etc.

Built-in Animated Components

• a
• button
• div
• span
• img

Hooks

useAnimatedValue(currentValue: number, animationFactory: ?Function): [AnimatedValue, boolean]

Easing

Predefined Animations

• Easing.ease: A simple inertial interaction, similar to an object slowly accelerating to speed.
• Easing.bounce: Provides a simple bouncing effect.
• Easing.back(s): Use with parallel() to create a simple effect where the object animates back slightly as the animation starts.
• Easing.elastic(bounciness): A simple elastic interaction, similar to a spring oscillating back and forth.
• Easing.bezier(x1, y1, x2, y2): Provides a cubic bezier curve, equivalent to CSS Transitions' transition-timing-function.

Standard Functions

• Easing.linear: A linear function, f(t) = t. Position correlates to elapsed time one to one.
• Easing.quad: A quadratic function, f(t) = t * t. Position equals the square of elapsed time.
• Easing.cubic: A cubic function, f(t) = t * t * t. Position equals the cube of elapsed time.
• Easing.poly: A power function. Position is equal to the Nth power of elapsed time.

Modifiers

• Easing.in(easing): Runs an easing function forwards.
• Easing.out(easing): Runs an easing function backwards.
• Easing.inOut(easing): Makes any easing function symmetrical. The easing function will run forwards for half of the duration, then backwards for the rest of the duration.

Additional Functions

• Easing.sin: A sinusoidal function.
• Easing.circle: A circular function.
• Easing.exp: An exponential function.
• Easing.step0: A stepping function, returns 1 for any positive value.
• Easing.step1A stepping function, returns 1 if a value is greater than or equal to 1.