The Basics

Guides

Guides (iOS)

Guides (Android)

Animated #

The Animated library is designed to make animations fluid, powerful, and easy to build and maintain. Animated focuses on declarative relationships between inputs and outputs, with configurable transforms in between, and simple start/stop methods to control time-based animation execution.

The simplest workflow for creating an animation is to to create an Animated.Value, hook it up to one or more style attributes of an animated component, and then drive updates via animations using Animated.timing():

Animated.timing(                            // Animate value over time
  this.state.fadeAnim,                      // The value to drive
  {
    toValue: 1,                             // Animate to final value of 1
  }
).start();                                  // Start the animation

Refer to the Animations guide to see additional examples of Animated in action.

Overview #

There are two value types you can use with Animated:

Animated.Value() for single values
Animated.ValueXY() for vectors

Animated.Value can bind to style properties or other props, and can be interpolated as well. A single Animated.Value can drive any number of properties.

Configuring animations #

Animated provides three types of animation types. Each animation type provides a particular animation curve that controls how your values animate from their initial value to the final value:

Animated.decay() starts with an initial velocity and gradually slows to a stop.
Animated.spring() provides a simple spring physics model.
Animated.timing() animates a value over time using easing functions.

In most cases, you will be using timing(). By default, it uses a symmetric easeInOut curve that conveys the gradual acceleration of an object to full speed and concludes by gradually decelerating to a stop.

Working with animations #

Animations are started by calling start() on your animation. start() takes a completion callback that will be called when the animation is done. If the animation finished running normally, the completion callback will be invoked with {finished: true}. If the animation is done because stop() was called on it before it could finish (e.g. because it was interrupted by a gesture or another animation), then it will receive {finished: false}.

Using the native driver #

By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.

You can use the native driver by specifying useNativeDriver: true in your animation configuration. See the Animations guide to learn more.

Animatable components #

Only animatable components can be animated. These special components do the magic of binding the animated values to the properties, and do targeted native updates to avoid the cost of the react render and reconciliation process on every frame. They also handle cleanup on unmount so they are safe by default.

createAnimatedComponent() can be used to make a component animatable.

Animated exports the following animatable components using the above wrapper:

Animated.Image
Animated.ScrollView
Animated.Text
Animated.View

Composing animations #

Animations can also be combined in complex ways using composition functions:

Animated.delay() starts an animation after a given delay.
Animated.parallel() starts a number of animations at the same time.
Animated.sequence() starts the animations in order, waiting for each to complete before starting the next.
Animated.stagger() starts animations in order and in parallel, but with successive delays.

Animations can also be chained together simply by setting the toValue of one animation to be another Animated.Value. See Tracking dynamic values in the Animations guide.

By default, if one animation is stopped or interrupted, then all other animations in the group are also stopped.

Combining animated values #

You can combine two animated values via addition, multiplication, division, or modulo to make a new animated value:

Interpolation #

The interpolate() function allows input ranges to map to different output ranges. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value. It uses lineal interpolation by default but also supports easing functions.

interpolate()

Read more about interpolation in the Animation guide.

Handling gestures and other events #

Gestures, like panning or scrolling, and other events can map directly to animated values using Animated.event(). This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.

Animated.event()

For example, when working with horizontal scrolling gestures, you would do the following in order to map event.nativeEvent.contentOffset.x to scrollX (an Animated.Value):

 onScroll={Animated.event(
   // scrollX = e.nativeEvent.contentOffset.x
   [{ nativeEvent: {
        contentOffset: {
          x: scrollX
        }
      }
    }]
 )}

Methods #

static decay(value, config) #

Animates a value from an initial velocity to zero based on a decay coefficient.

Config is an object that may have the following options:

velocity: Initial velocity. Required.
deceleration: Rate of decay. Default 0.997.
useNativeDriver: Uses the native driver when true. Default false.

static timing(value, config) #

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:

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.
useNativeDriver: Uses the native driver when true. Default false.

static spring(value, config) #

Spring animation based on Rebound and Origami. 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:

friction: Controls "bounciness"/overshoot. Default 7.
tension: Controls speed. Default 40.
useNativeDriver: Uses the native driver when true. Default false.

static add(a, b) #

Creates a new Animated value composed from two Animated values added together.

static divide(a, b) #

Creates a new Animated value composed by dividing the first Animated value by the second Animated value.

static multiply(a, b) #

Creates a new Animated value composed from two Animated values multiplied together.

static modulo(a, modulus) #

Creates a new Animated value that is the (non-negative) modulo of the provided Animated value

static diffClamp(a, min, max) #

Create a new Animated value that is limited between 2 values. It uses the difference between the last value so even if the value is far from the bounds it will start changing when the value starts getting closer again. (value = clamp(value + diff, min, max)).

This is useful with scroll events, for example, to show the navbar when scrolling up and to hide it when scrolling down.

static delay(time) #

Starts an animation after the given delay.

static sequence(animations) #

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.

static parallel(animations, config?) #

Starts an array of animations all at the same time. By default, if one of the animations is stopped, they will all be stopped. You can override this with the stopTogether flag.

static stagger(time, animations) #

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

static event(argMapping, config?) #

Takes an array of mappings and extracts values from each arg accordingly, then calls setValue on the mapped outputs. e.g.

 onScroll={Animated.event(
   [{nativeEvent: {contentOffset: {x: this._scrollX}}}]
   {listener},          // Optional async listener
 )
 ...
 onPanResponderMove: Animated.event([
   null,                // raw event arg ignored
   {dx: this._panX},    // gestureState arg
 ]),

Config is an object that may have the following options:

listener: Optional async listener.
useNativeDriver: Uses the native driver when true. Default false.

static createAnimatedComponent(Component) #

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

Properties #

Value: AnimatedValue #

Standard value class for driving animations. Typically initialized with new Animated.Value(0);

ValueXY: AnimatedValueXY #

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

Interpolation: AnimatedInterpolation #

exported to use the Interpolation type in flow

class AnimatedValue #

Standard value for driving animations. One Animated.Value can drive multiple properties in a synchronized fashion, but can only be driven by one mechanism at a time. Using a new mechanism (e.g. starting a new animation, or calling setValue) will stop any previous ones.

Methods #

constructor(value) #

setValue(value) #

Directly set the value. This will stop any animations running on the value and update all the bound properties.

setOffset(offset) #

Sets an offset that is applied on top of whatever value is set, whether via setValue, an animation, or Animated.event. Useful for compensating things like the start of a pan gesture.

flattenOffset(0) #

Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.

extractOffset(0) #

Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.

addListener(callback) #

Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.

removeListener(id) #

removeAllListeners(0) #

stopAnimation(callback?) #

Stops any running animation or tracking. callback is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.

interpolate(config) #

Interpolates the value before updating the property, e.g. mapping 0-1 to 0-10.

animate(animation, callback) #

Typically only used internally, but could be used by a custom Animation class.

stopTracking(0) #

Typically only used internally.

track(tracking) #

Typically only used internally.

class AnimatedValueXY #

2D Value for driving 2D animations, such as pan gestures. Almost identical API to normal Animated.Value, but multiplexed. Contains two regular Animated.Values under the hood.

Example #

 class DraggableView extends React.Component {
   constructor(props) {
     super(props);
     this.state = {
       pan: new Animated.ValueXY(), // inits to zero
     };
     this.state.panResponder = PanResponder.create({
       onStartShouldSetPanResponder: () => true,
       onPanResponderMove: Animated.event([null, {
         dx: this.state.pan.x, // x,y are Animated.Value
         dy: this.state.pan.y,
       }]),
       onPanResponderRelease: () => {
         Animated.spring(
           this.state.pan,         // Auto-multiplexed
           {toValue: {x: 0, y: 0}} // Back to zero
         ).start();
       },
     });
   }
   render() {
     return (
       <Animated.View
         {...this.state.panResponder.panHandlers}
         style={this.state.pan.getLayout()}>
         {this.props.children}
       </Animated.View>
     );
   }
 }

Methods #

constructor(valueIn?) #

setValue(value) #

setOffset(offset) #

flattenOffset(0) #

extractOffset(0) #

stopAnimation(callback?) #

addListener(callback) #

removeListener(id) #

removeAllListeners(0) #

getLayout(0) #

Converts {x, y} into {left, top} for use in style, e.g.

 style={this.state.anim.getLayout()}

getTranslateTransform(0) #

Converts {x, y} into a useable translation transform, e.g.

 style={{
   transform: this.state.anim.getTranslateTransform()
 }}

class AnimatedInterpolation #

Methods #

constructor(parent, config) #

interpolate(config) #

You can edit the content above on GitHub and send us a pull request!

Examples #

Edit on GitHub

'use strict';

var React = require('react');
var ReactNative = require('react-native');
var {
  Animated,
  Easing,
  StyleSheet,
  Text,
  View,
} = ReactNative;
var UIExplorerButton = require('./UIExplorerButton');

exports.framework = 'React';
exports.title = 'Animated - Examples';
exports.description = 'Animated provides a powerful ' +
  'and easy-to-use API for building modern, ' +
  'interactive user experiences.';

exports.examples = [
  {
    title: 'FadeInView',
    description: 'Uses a simple timing animation to ' +
      'bring opacity from 0 to 1 when the component ' +
      'mounts.',
    render: function() {
      class FadeInView extends React.Component {
        state: any;

        constructor(props) {
          super(props);
          this.state = {
            fadeAnim: new Animated.Value(0), // opacity 0
          };
        }
        componentDidMount() {
          Animated.timing(       // Uses easing functions
            this.state.fadeAnim, // The value to drive
            {
              toValue: 1,        // Target
              duration: 2000,    // Configuration
            },
          ).start();             // Don't forget start!
        }
        render() {
          return (
            <Animated.View   // Special animatable View
              style={{
                opacity: this.state.fadeAnim,  // Binds
              }}>
              {this.props.children}
            </Animated.View>
          );
        }
      }
      class FadeInExample extends React.Component {
        state: any;

        constructor(props) {
          super(props);
          this.state = {
            show: true,
          };
        }
        render() {
          return (
            <View>
              <UIExplorerButton onPress={() => {
                  this.setState((state) => (
                    {show: !state.show}
                  ));
                }}>
                Press to {this.state.show ?
                  'Hide' : 'Show'}
              </UIExplorerButton>
              {this.state.show && <FadeInView>
                <View style={styles.content}>
                  <Text>FadeInView</Text>
                </View>
              </FadeInView>}
            </View>
          );
        }
      }
      return <FadeInExample />;
    },
  },
  {
    title: 'Transform Bounce',
    description: 'One `Animated.Value` is driven by a ' +
      'spring with custom constants and mapped to an ' +
      'ordered set of transforms.  Each transform has ' +
      'an interpolation to convert the value into the ' +
      'right range and units.',
    render: function() {
      this.anim = this.anim || new Animated.Value(0);
      return (
        <View>
          <UIExplorerButton onPress={() => {
            Animated.spring(this.anim, {
              toValue: 0,   // Returns to the start
              velocity: 3,  // Velocity makes it move
              tension: -10, // Slow
              friction: 1,  // Oscillate a lot
            }).start(); }}>
            Press to Fling it!
          </UIExplorerButton>
          <Animated.View
            style={[styles.content, {
              transform: [   // Array order matters
                {scale: this.anim.interpolate({
                  inputRange: [0, 1],
                  outputRange: [1, 4],
                })},
                {translateX: this.anim.interpolate({
                  inputRange: [0, 1],
                  outputRange: [0, 500],
                })},
                {rotate: this.anim.interpolate({
                  inputRange: [0, 1],
                  outputRange: [
                    '0deg', '360deg' // 'deg' or 'rad'
                  ],
                })},
              ]}
            ]}>
            <Text>Transforms!</Text>
          </Animated.View>
        </View>
      );
    },
  },
  {
    title: 'Composite Animations with Easing',
    description: 'Sequence, parallel, delay, and ' +
      'stagger with different easing functions.',
    render: function() {
      this.anims = this.anims || [1,2,3].map(
        () => new Animated.Value(0)
      );
      return (
        <View>
          <UIExplorerButton onPress={() => {
            var timing = Animated.timing;
            Animated.sequence([ // One after the other
              timing(this.anims[0], {
                toValue: 200,
                easing: Easing.linear,
              }),
              Animated.delay(400), // Use with sequence
              timing(this.anims[0], {
                toValue: 0,
                easing: Easing.elastic(2), // Springy
              }),
              Animated.delay(400),
              Animated.stagger(200,
                this.anims.map((anim) => timing(
                  anim, {toValue: 200}
                )).concat(
                this.anims.map((anim) => timing(
                  anim, {toValue: 0}
                ))),
              ),
              Animated.delay(400),
              Animated.parallel([
                Easing.inOut(Easing.quad), // Symmetric
                Easing.back(1.5),  // Goes backwards first
                Easing.ease        // Default bezier
              ].map((easing, ii) => (
                timing(this.anims[ii], {
                  toValue: 320, easing, duration: 3000,
                })
              ))),
              Animated.delay(400),
              Animated.stagger(200,
                this.anims.map((anim) => timing(anim, {
                  toValue: 0,
                  easing: Easing.bounce, // Like a ball
                  duration: 2000,
                })),
              ),
            ]).start(); }}>
            Press to Animate
          </UIExplorerButton>
          {['Composite', 'Easing', 'Animations!'].map(
            (text, ii) => (
              <Animated.View
                key={text}
                style={[styles.content, {
                  left: this.anims[ii]
                }]}>
                <Text>{text}</Text>
              </Animated.View>
            )
          )}
        </View>
      );
    },
  },
  {
    title: 'Continuous Interactions',
    description: 'Gesture events, chaining, 2D ' +
      'values, interrupting and transitioning ' +
      'animations, etc.',
    render: () => (
      <Text>Checkout the Gratuitous Animation App!</Text>
    ),
  }
];

var styles = StyleSheet.create({
  content: {
    backgroundColor: 'deepskyblue',
    borderWidth: 1,
    borderColor: 'dodgerblue',
    padding: 20,
    margin: 20,
    borderRadius: 10,
    alignItems: 'center',
  },
});

Run this example

← Prev Next →

The Basics

Guides

Guides (iOS)

Guides (Android)

components

apis

Animated #

Overview #

Configuring animations #

Working with animations #

Using the native driver #

Animatable components #

Composing animations #

Combining animated values #

Interpolation #

Handling gestures and other events #

Methods #

static decay(value, config) #

static timing(value, config) #

static spring(value, config) #

static add(a, b) #

static divide(a, b) #

static multiply(a, b) #

static modulo(a, modulus) #

static diffClamp(a, min, max) #

static delay(time) #

static sequence(animations) #

static parallel(animations, config?) #

static stagger(time, animations) #

static event(argMapping, config?) #

static createAnimatedComponent(Component) #

Properties #

Value: AnimatedValue #

ValueXY: AnimatedValueXY #

Interpolation: AnimatedInterpolation #

class AnimatedValue #

Methods #

constructor(value) #

setValue(value) #

setOffset(offset) #

flattenOffset(0) #

extractOffset(0) #

addListener(callback) #

removeListener(id) #

removeAllListeners(0) #

stopAnimation(callback?) #

interpolate(config) #

animate(animation, callback) #

stopTracking(0) #

track(tracking) #

class AnimatedValueXY #

Example #

Methods #

constructor(valueIn?) #

setValue(value) #

setOffset(offset) #

flattenOffset(0) #

extractOffset(0) #

stopAnimation(callback?) #

addListener(callback) #

removeListener(id) #

removeAllListeners(0) #

getLayout(0) #

getTranslateTransform(0) #

class AnimatedInterpolation #

Methods #

constructor(parent, config) #

interpolate(config) #

Examples #