animation library

The Flutter animation system.

To use, import package:flutter/animation.dart.

This library provides basic building blocks for implementing animations in Flutter. Other layers of the framework use these building blocks to provide advanced animation support for applications. For example, the widget library includes ImplicitlyAnimatedWidgets and AnimatedWidgets that make it easy to animate certain properties of a Widget. If those animated widgets are not sufficient for a given use case, the basic building blocks provided by this library can be used to implement custom animated effects.

This library depends only on core Dart libraries and the physics.dart library.

Foundations: the Animation class

Flutter represents an animation as a value that changes over a given duration, and that value may be of any type. For example, it could be a double indicating the current opacity of a Widget as it fades out. Or, it could be the current background Color of a widget that transitions smoothly from one color to another. The current value of an animation is represented by an Animation object, which is the central class of the animation library. In addition to the current animation value, the Animation object also stores the current AnimationStatus. The status indicates whether the animation is currently conceptually running from the beginning to the end or the other way around. It may also indicate that the animation is currently stopped at the beginning or the end.

Other objects can register listeners on an Animation to be informed whenever the animation value and/or the animation status changes. A Widget may register such a value listener via Animation.addListener to rebuild itself with the current animation value whenever that value changes. For example, a widget might listen to an animation to update its opacity to the animation's value every time that value changes. Likewise, registering a status listener via Animation.addStatusListener may be useful to trigger another action when the current animation has ended.

As an example, the following video shows the changes over time in the current animation status and animation value for the opacity animation of a widget. This Animation is driven by an AnimationController (see next section). Before the animation triggers, the animation status is "dismissed" and the value is 0.0. As the value runs from 0.0 to 1.0 to fade in the widget, the status changes to "forward". When the widget is fully faded in at an animation value of 1.0 the status is "completed". When the animation triggers again to fade the widget back out, the animation status changes to "reverse" and the animation value runs back to 0.0. At that point the widget is fully faded out and the animation status switches back to "dismissed" until the animation is triggered again.

Although you can't instantiate Animation directly (it is an abstract class), you can create one using an AnimationController.

Powering animations: AnimationController

An AnimationController is a special kind of Animation that advances its animation value whenever the device running the application is ready to display a new frame (typically, this rate is around 60 values per second). An AnimationController can be used wherever an Animation is expected. As the name implies, an AnimationController also provides control over its Animation: It implements methods to stop the animation at any time and to run it forward as well as in the reverse direction.

By default, an AnimationController increases its animation value linearly over the given duration from 0.0 to 1.0 when run in the forward direction. For many use cases you might want the value to be of a different type, change the range of the animation values, or change how the animation moves between values. This is achieved by wrapping the animation: Wrapping it in an Animatable (see below) changes the range of animation values to a different range or type (for example to animate Colors or Rects). Furthermore, a Curve can be applied to the animation by wrapping it in a CurvedAnimation. Instead of linearly increasing the animation value, a curved animation changes its value according to the provided curve. The framework ships with many built-in curves (see Curves). As an example, Curves.easeOutCubic increases the animation value quickly at the beginning of the animation and then slows down until the target value is reached:

Animating different types: Animatable

An Animatable<T> is an object that takes an Animation<double> as input and produces a value of type T. Objects of these types can be used to translate the animation value range of an AnimationController (or any other Animation of type double) to a different range. That new range doesn't even have to be of type double anymore. With the help of an Animatable like a Tween or a TweenSequence (see sections below) an AnimationController can be used to smoothly transition Colors, Rects, Sizes and many more types from one value to another over a given duration.

Interpolating values: Tweens

A Tween is applied to an Animation of type double to change the range and type of the animation value. For example, to transition the background of a Widget smoothly between two Colors, a ColorTween can be used. Each Tween specifies a start and an end value. As the animation value of the Animation powering the Tween progresses from 0.0 to 1.0 it produces interpolated values between its start and end value. The values produced by the Tween usually move closer and closer to its end value as the animation value of the powering Animation approaches 1.0.

The following video shows example values produced by an IntTween, a Tween<double>, and a ColorTween as the animation value runs from 0.0 to 1.0 and back to 0.0:

An Animation or AnimationController can power multiple Tweens. For example, to animate the size and the color of a widget in parallel, create one AnimationController that powers a SizeTween and a ColorTween.

The framework ships with many Tween subclasses (IntTween, SizeTween, RectTween, etc.) to animate common properties.

Staggered animations: TweenSequences

A TweenSequence can help animate a given property smoothly in stages. Each Tween in the sequence is responsible for a different stage and has an associated weight. When the animation runs, the stages execute one after another. For example, let's say you want to animate the background of a widget from yellow to green and then, after a short pause, to red. For this you can specify three tweens within a tween sequence: One ColorTween animating from yellow to green, one ConstantTween that just holds the color green, and another ColorTween animating from green to red. For each tween you need to pick a weight indicating the ratio of time spent on that tween compared to all other tweens. If we assign a weight of 2 to both of the ColorTweens and a weight of 1 to the ConstantTween the transition described by the ColorTweens would take twice as long as the ConstantTween. A TweenSequence is driven by an Animation just like a regular Tween: As the powering Animation runs from 0.0 to 1.0 the TweenSequence runs through all of its stages.

The following video shows the animation described in the previous paragraph:

See also:

• Introduction to animations on flutter.dev.
• Animations tutorial on flutter.dev.
• Sample app, which showcases Flutter's animation features.
• ImplicitlyAnimatedWidget and its subclasses, which are Widgets that implicitly animate changes to their properties.
• AnimatedWidget and its subclasses, which are Widgets that take an explicit Animation to animate their properties.