AnimationController class

A controller for an animation.

This class lets you perform tasks such as:

• Play an animation forward or in reverse, or stop an animation.
• Set the animation to a specific value.
• Define the upperBound and lowerBound values of an animation.
• Create a fling animation effect using a physics simulation.

By default, an AnimationController linearly produces values that range from 0.0 to 1.0, during a given duration.

When the animation is actively animating, the animation controller generates a new value each time the device running your app is ready to display a new frame (typically, this rate is around 60–120 values per second). If the animation controller is associated with a State through a TickerProvider, then its updates will be silenced when that State's subtree is disabled as defined by TickerMode; time will still elapse, and methods like forward and stop can still be called and will change the value, but the controller will not generate new values on its own.

Ticker providers

An AnimationController needs a TickerProvider, which is configured using the vsync argument on the constructor. The constructor uses the TickerProvider to create a Ticker, which the AnimationController uses to step through the animation it controls.

For advice on obtaining a ticker provider, see TickerProvider. Typically the relevant State serves as the ticker provider, after applying a suitable mixin (like SingleTickerProviderStateMixin) to cause the State subclass to implement TickerProvider.

Life cycle

An AnimationController should be disposed when it is no longer needed. This reduces the likelihood of leaks. When used with a StatefulWidget, it is common for an AnimationController to be created in the State.initState method and then disposed in the State.dispose method.

Using Futures with AnimationController

The methods that start animations return a TickerFuture object which completes when the animation completes successfully, and never throws an error; if the animation is canceled, the future never completes. This object also has a TickerFuture.orCancel property which returns a future that completes when the animation completes successfully, and completes with an error when the animation is aborted.

This can be used to write code such as the fadeOutAndUpdateState method below.

class Foo extends StatefulWidget {
  const Foo({ super.key, required this.duration });

  final Duration duration;

  @override
  State<Foo> createState() => _FooState();
}

class _FooState extends State<Foo> with SingleTickerProviderStateMixin {
  late AnimationController _controller;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(
      vsync: this, // the SingleTickerProviderStateMixin
      duration: widget.duration,
    );
  }

  @override
  void didUpdateWidget(Foo oldWidget) {
    super.didUpdateWidget(oldWidget);
    _controller.duration = widget.duration;
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Container(); // ...
  }
}

Future<void> fadeOutAndUpdateState() async {
  try {
    await fadeAnimationController.forward().orCancel;
    await sizeAnimationController.forward().orCancel;
    setState(() {
      dismissed = true;
    });
  } on TickerCanceled {
    // the animation got canceled, probably because we were disposed
  }
}

The assumption in the code above is that the animation controllers are being disposed in the State subclass' override of the State.dispose method. Since disposing the controller cancels the animation (raising a TickerCanceled exception), the code here can skip verifying whether State.mounted is still true at each step. (Again, this assumes that the controllers are created in State.initState and disposed in State.dispose, as described in the previous section.)

See also:

• Tween, the base class for converting an AnimationController to a range of values of other types.