🎬 Simple Animations

Simple Animations simplifies the process of creating beautiful custom animations:

• Easily create custom animations in stateless widgets
• Animate multiple properties at once
• Create staggered animations within seconds
• Simplified working with AnimationController instances
• Debug animations

Table of Contents

Quickstart

• Animation Builder - Quickstart
• Movie Tween - Quickstart
• Animation Mixin - Quickstart
• Animation Developer Tools - Quickstart

Animation Builder

• Essential parts of the animation
• PlayAnimationBuilder
• LoopAnimationBuilder
• MirrorAnimationBuilder
• CustomAnimationBuilder

Movie Tween

• Basic usage pattern
• Scenes
• Animate properties
• Curves
• Extrapolation
• Use developer tools
• Animation duration

Animation Mixin

• Basic usage pattern
• Create multiple AnimationController instances

Shortcuts for AnimationController

Animation Developer Tools

• Basic usage pattern
• Features and tricks

Quickstart

Dive right in and let the code speak for itself.

Animation Builder - Quickstart

Animation Builder widgets are a powerful way to create custom animations.

import 'dart:math';

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

class ResizeCubeAnimation extends StatelessWidget {
  const ResizeCubeAnimation({super.key});

  @override
  Widget build(BuildContext context) {
    // PlayAnimationBuilder plays animation once
    return PlayAnimationBuilder<double>(
      tween: Tween(begin: 100.0, end: 200.0), // 100.0 to 200.0
      duration: const Duration(seconds: 1), // for 1 second
      builder: (context, value, _) {
        return Container(
          width: value, // use animated value
          height: value,
          color: Colors.blue,
        );
      },
      onCompleted: () {
        // do something ...
      },
    );
  }
}

class RotatingBox extends StatelessWidget {
  const RotatingBox({super.key});

  @override
  Widget build(BuildContext context) {
    // LoopAnimationBuilder plays forever: from beginning to end
    return LoopAnimationBuilder<double>(
      tween: Tween(begin: 0.0, end: 2 * pi), // 0° to 360° (2π)
      duration: const Duration(seconds: 2), // for 2 seconds per iteration
      builder: (context, value, _) {
        return Transform.rotate(
          angle: value, // use value
          child: Container(color: Colors.blue, width: 100, height: 100),
        );
      },
    );
  }
}

class ColorFadeLoop extends StatelessWidget {
  const ColorFadeLoop({super.key});

  @override
  Widget build(BuildContext context) {
    // MirrorAnimationBuilder plays forever: alternating forward and backward
    return MirrorAnimationBuilder<Color?>(
      tween: ColorTween(begin: Colors.red, end: Colors.blue), // red to blue
      duration: const Duration(seconds: 5), // for 5 seconds per iteration
      builder: (context, value, _) {
        return Container(
          color: value, // use animated value
          width: 100,
          height: 100,
        );
      },
    );
  }
}

Read guide or watch examples.

---

Movie Tween - Quickstart

Movie Tween combines multiple tweens into one, including timeline control and value extrapolation.

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

// Simple staggered tween
final tween1 = MovieTween()
  ..tween(
    'width',
    Tween(begin: 0.0, end: 100),
    duration: const Duration(milliseconds: 1500),
    curve: Curves.easeIn,
  ).thenTween(
    'width',
    Tween(begin: 100, end: 200),
    duration: const Duration(milliseconds: 750),
    curve: Curves.easeOut,
  );

// Design tween by composing scenes
final tween2 = MovieTween()
  ..scene(
        begin: const Duration(milliseconds: 0),
        duration: const Duration(milliseconds: 500),
      )
      .tween('width', Tween<double>(begin: 0.0, end: 400.0))
      .tween('height', Tween<double>(begin: 500.0, end: 200.0))
      .tween('color', ColorTween(begin: Colors.red, end: Colors.blue))
  ..scene(
    begin: const Duration(milliseconds: 700),
    end: const Duration(milliseconds: 1200),
  ).tween('width', Tween<double>(begin: 400.0, end: 500.0));

// Type-safe alternative
final width = MovieTweenProperty<double>();
final color = MovieTweenProperty<Color?>();

final tween3 = MovieTween()
  ..tween<double>(width, Tween(begin: 0.0, end: 100))
  ..tween<Color?>(color, ColorTween(begin: Colors.red, end: Colors.blue));

Read guide or watch examples.

---

Animation Mixin - Quickstart

The Animation Mixin manages AnimationController instances for you. No more boilerplate code.

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

class MyWidget extends StatefulWidget {
  const MyWidget({super.key});

  @override
  _MyWidgetState createState() => _MyWidgetState();
}

// Add AnimationMixin
class _MyWidgetState extends State<MyWidget> with AnimationMixin {
  late Animation<double> size;

  @override
  void initState() {
    // The AnimationController instance `controller` is already wired up.
    // Just connect it to the tweens.
    size = Tween<double>(begin: 0.0, end: 200.0).animate(controller);

    controller.play(); // start the animation playback

    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Container(
      width: size.value, // use animated value
      height: size.value,
      color: Colors.red,
    );
  }
}

Read guide or watch examples.

---

Animation Developer Tools - Quickstart

The Animation Developer Tools widget helps you fine-tune animations. It allows you to pause anywhere, scrub through the timeline, speed up, slow down, or focus on a specific part of an animation.

Read guide

Animation Builder

Animation Builder enables developers to craft custom animations with simple widgets.

Essential parts of the animation

You need three things to create an animation:

• tween: What value is changing within the animation?
• duration: How long does the animation take?
• builder: How does the UI respond to the changing value?

Tween

The tween describes your animation. It usually changes a value from A to B. Tweens describe what will happen, but not how fast it will happen.

import 'package:flutter/material.dart';

// Animate a color from red to blue
var colorTween = ColorTween(begin: Colors.red, end: Colors.blue);

// Animate a double value from 0 to 100
var doubleTween = Tween<double>(begin: 0.0, end: 100.0);

To animate multiple properties, use a Movie Tween.

Duration

The duration is the time the animation takes.

Builder

The builder is a function that is called for each newly rendered frame of your animation. It takes three parameters: context, value and child.

• context is your Flutter BuildContext

• value is the current value produced by the tween. If your tween is Tween<double>(begin: 0.0, end: 100.0), the value is a double somewhere between 0.0 and 100.0.

• child can be a widget that you pass into an Animation Builder widget. This widget stays constant and is not affected by the animation.

How often the builder function is called depends on the animation duration and the frame rate of the device.

Limit the frame rate

All Animation Builder widgets accept an optional fps parameter. This limits how often the widget rebuilds while the animation is running. It can be useful for expensive custom animations where you do not need to rebuild at the device's full frame rate.

PlayAnimationBuilder

The PlayAnimationBuilder is a widget that plays an animation once.

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

// Use type `Color?` because ColorTween produces type `Color?`
var widget = PlayAnimationBuilder<Color?>(
  tween: ColorTween(begin: Colors.red, end: Colors.blue), // define tween
  duration: const Duration(seconds: 5), // define duration
  builder: (context, value, _) {
    return Container(
      color: value, // use animated color
      width: 100,
      height: 100,
    );
  },
);

Delay

By default, animations will play automatically. You can set a delay to make PlayAnimationBuilder wait for a given amount of time.

The delay is ignored when developerMode is enabled because the Animation Developer Tools take over playback control.

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

var widget = PlayAnimationBuilder<Color?>(
  tween: ColorTween(begin: Colors.red, end: Colors.blue),
  duration: const Duration(seconds: 5),
  delay: const Duration(seconds: 2), // add delay
  builder: (context, value, _) {
    return Container(color: value, width: 100, height: 100);
  },
);

Non-linear motion

You can make your animation more appealing by applying non-linear motion behavior to it. Just pass a curve into the widget.

Flutter comes with a set of predefined curves inside the Curves class.

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

var widget = PlayAnimationBuilder<Color?>(
  tween: ColorTween(begin: Colors.red, end: Colors.blue),
  duration: const Duration(seconds: 5),
  curve: Curves.easeInOut, // specify curve
  builder: (context, value, _) {
    return Container(color: value, width: 100, height: 100);
  },
);

Animation lifecycle

You can react to the animation status by setting callbacks.

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

var widget = PlayAnimationBuilder<Color?>(
  // lifecycle callbacks
  onStarted: () => debugPrint('Animation started'),
  onCompleted: () => debugPrint('Animation complete'),

  tween: ColorTween(begin: Colors.red, end: Colors.blue),
  duration: const Duration(seconds: 5),
  builder: (context, value, _) =>
      Container(color: value, width: 100, height: 100),
);

Using child widgets

Parts of the UI that are not affected by the animated value can be passed as a Widget into the child property. That Widget is available within the builder function. It will not rebuild when the animated value changes, which improves performance.

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

var widget = PlayAnimationBuilder<Color?>(
  tween: ColorTween(begin: Colors.red, end: Colors.blue),
  duration: const Duration(seconds: 5),
  // child gets passed into builder function
  builder: (context, value, child) {
    return Container(
      color: value,
      width: 100,
      height: 100,
      child: child, // use child
    );
  },
  child: const Text('Hello World'), // specify child widget
);

Using keys

If Flutter swaps out a PlayAnimationBuilder with a different PlayAnimationBuilder in a rebuild, it may recycle the first one. This may lead to undesired behavior. In such a case, use the key property.

You can watch this introduction to Key.

App example

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

void main() => runApp(
  const MaterialApp(
    home: Scaffold(body: Center(child: AnimatedGreenBox())),
  ),
);

class AnimatedGreenBox extends StatelessWidget {
  const AnimatedGreenBox({super.key});

  @override
  Widget build(BuildContext context) {
    return PlayAnimationBuilder<double>(
      // specify tween (from 50.0 to 200.0)
      tween: Tween<double>(begin: 50.0, end: 200.0),

      // set a duration
      duration: const Duration(seconds: 5),

      // set a curve
      curve: Curves.easeInOut,

      // use builder function
      builder: (context, value, child) {
        // apply animated value obtained from builder function parameter
        return Container(
          width: value,
          height: value,
          color: Colors.green,
          child: child,
        );
      },
      child: const Text('Hello World'),
    );
  }
}

LoopAnimationBuilder

A LoopAnimationBuilder repeatedly plays the animation from the start to the end over and over again.

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

var widget = LoopAnimationBuilder<Color?>(
  // mandatory parameters
  tween: ColorTween(begin: Colors.red, end: Colors.blue),
  duration: const Duration(seconds: 5),
  builder: (context, value, child) {
    return Container(color: value, width: 100, height: 100, child: child);
  },
  // optional parameters
  curve: Curves.easeInOut,
  child: const Text('Hello World'),
);

MirrorAnimationBuilder

A MirrorAnimationBuilder repeatedly plays the animation from the start to the end, then reverses to the start, then plays forward again, and so on.

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

var widget = MirrorAnimationBuilder<Color?>(
  // mandatory parameters
  tween: ColorTween(begin: Colors.red, end: Colors.blue),
  duration: const Duration(seconds: 5),
  builder: (context, value, child) {
    return Container(color: value, width: 100, height: 100, child: child);
  },
  // optional parameters
  curve: Curves.easeInOut,
  child: const Text('Hello World'),
);

CustomAnimationBuilder

Use CustomAnimationBuilder if the animation widgets discussed above aren't sufficient for your use case. In addition to all parameters mentioned for PlayAnimationBuilder, it lets you actively control the animation.

Control the animation

The control parameter can be set to the following values:

Control.VALUE	Description
stop	Stops the animation at the current position.
play	Plays the animation from the current position to the end.
playReverse	Plays the animation from the current position in reverse to the start.
playFromStart	Resets the animation position to the beginning (0.0) and starts playing to the end.
playReverseFromEnd	Resets the position of the animation to the end (1.0) and starts playing backwards to the start.
loop	Endlessly plays the animation from the start to the end.
mirror	Endlessly plays the animation from the start to the end, then reverses to the start, then plays forward again, and so on.

You can bind the control value to a state variable and change it during the animation. The CustomAnimationBuilder will adapt to that.

When developerMode is enabled, CustomAnimationBuilder does not apply the control instruction. The connected Animation Developer Tools control playback instead.

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

void main() => runApp(
  const MaterialApp(
    home: Scaffold(body: Center(child: SwappingButton())),
  ),
);

class SwappingButton extends StatefulWidget {
  const SwappingButton({super.key});

  @override
  _SwappingButtonState createState() => _SwappingButtonState();
}

class _SwappingButtonState extends State<SwappingButton> {
  var control = Control.play; // define variable

  void _toggleDirection() {
    setState(() {
      // let the animation play in the opposite direction
      control = control == Control.play ? Control.playReverse : Control.play;
    });
  }

  @override
  Widget build(BuildContext context) {
    return CustomAnimationBuilder<double>(
      control: control, // bind variable to control instruction
      tween: Tween<double>(begin: -100.0, end: 100.0),
      duration: const Duration(seconds: 1),
      builder: (context, value, child) {
        // moves child from left to right
        return Transform.translate(offset: Offset(value, 0), child: child);
      },
      child: OutlinedButton(
        // clicking button changes animation direction
        onPressed: _toggleDirection,
        child: const Text('Swap'),
      ),
    );
  }
}

Start position

By default, the animation starts from the beginning (0.0). You can change this by setting the startPosition parameter. It can be set to a value between 0.0 (beginning) and 1.0 (end).

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

var widget = CustomAnimationBuilder<Color?>(
  control: Control.play,
  startPosition: 0.5, // set start position at 50%
  duration: const Duration(seconds: 5),
  tween: ColorTween(begin: Colors.red, end: Colors.blue),
  builder: (context, value, child) {
    return Container(color: value, width: 100, height: 100);
  },
);

Animation lifecycle

You can react to the animation status by setting callbacks.

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

var widget = CustomAnimationBuilder<Color?>(
  // lifecycle callbacks
  onStarted: () => debugPrint('Animation started'),
  onCompleted: () => debugPrint('Animation complete'),

  tween: ColorTween(begin: Colors.red, end: Colors.blue),
  duration: const Duration(seconds: 5),
  builder: (context, value, child) {
    return Container(color: value, width: 100, height: 100);
  },
);

It's also possible to directly access the AnimationStatusListener of the internal AnimationController.

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

var widget = CustomAnimationBuilder<Color?>(
  animationStatusListener: (AnimationStatus status) {
    // provide listener
    if (status == AnimationStatus.completed) {
      debugPrint('Animation completed!');
    }
  },
  tween: ColorTween(begin: Colors.red, end: Colors.blue),
  duration: const Duration(seconds: 5),
  builder: (context, value, child) {
    return Container(color: value, width: 100, height: 100);
  },
);

Movie Tween

Movie Tween combines multiple tweens into one, including timeline control and value extrapolation.

Basic usage pattern

Create a new MovieTween and use tween() to tween multiple values:

final tween = MovieTween();

tween.tween(
  'width',
  Tween(begin: 0.0, end: 100.0),
  duration: const Duration(milliseconds: 700),
);

tween.tween(
  'height',
  Tween(begin: 100.0, end: 200.0),
  duration: const Duration(milliseconds: 700),
);

You can use .. to get a nice builder-style syntax:

final tween = MovieTween()
  ..tween(
    'width',
    Tween(begin: 0.0, end: 100.0),
    duration: const Duration(milliseconds: 700),
  )
  ..tween(
    'height',
    Tween(begin: 100.0, end: 200.0),
    duration: const Duration(milliseconds: 700),
  );

To avoid repeating yourself, you can use scene() to create an explicit scene and apply both tweens to it:

final tween = MovieTween();

tween.scene(duration: const Duration(milliseconds: 700))
  ..tween('width', Tween(begin: 0.0, end: 100.0))
  ..tween('height', Tween(begin: 100.0, end: 200.0));

Calling tween() creates a scene as well. Therefore you can just call thenTween() to create staggered animations.

final tween = MovieTween();

tween
    .tween(
      'width',
      Tween(begin: 0.0, end: 100.0),
      duration: const Duration(milliseconds: 700),
    )
    .thenTween(
      'width',
      Tween(begin: 100.0, end: 200.0),
      duration: const Duration(milliseconds: 500),
    );

You can use a PlayAnimationBuilder, for example, to bring the MovieTween to life:

@override
Widget build(BuildContext context) {
  // create tween
  var tween = MovieTween()
    ..scene(duration: const Duration(milliseconds: 700))
        .tween('width', Tween<double>(begin: 0.0, end: 100.0))
        .tween('height', Tween<double>(begin: 300.0, end: 200.0));

  return PlayAnimationBuilder<Movie>(
    tween: tween, // provide tween
    duration: tween.duration, // total duration obtained from MovieTween
    builder: (context, value, _) {
      return Container(
        width: value.get('width'), // get animated width value
        height: value.get('height'), // get animated height value
        color: Colors.yellow,
      );
    },
  );
}

MovieTween animates to a Movie that offers a get() method to obtain a single animated value.

Type-safe properties

String keys are concise, but MovieTweenProperty<T> gives you typed access to values and avoids accidental key reuse.

final width = MovieTweenProperty<double>();
final color = MovieTweenProperty<Color?>();

final tween = MovieTween()
  ..tween<double>(width, Tween(begin: 0.0, end: 100.0))
  ..tween<Color?>(color, ColorTween(begin: Colors.red, end: Colors.blue));

final movie = tween.transform(0.5);

final currentWidth = width.from(movie); // type: double
final currentColor = color.from(movie); // type: Color?

Scenes

A MovieTween can consist of multiple scenes with each scene having multiple tweened properties. Those scenes can be created

• implicitly using tween() or thenTween(),
• explicitly using scene() or thenFor().

final tween = MovieTween();

// implicit scenes
final sceneA1 = tween.tween(
  'x',
  Tween(begin: 0.0, end: 1.0),
  duration: const Duration(milliseconds: 700),
);

final sceneA2 = sceneA1.thenTween(
  'x',
  Tween(begin: 1.0, end: 2.0),
  duration: const Duration(milliseconds: 500),
);

// explicit scenes
final sceneB1 = tween
    .scene(duration: const Duration(milliseconds: 700))
    .tween('x', Tween(begin: 0.0, end: 1.0));

final sceneB2 = sceneB1
    .thenFor(duration: const Duration(milliseconds: 500))
    .tween('x', Tween(begin: 1.0, end: 2.0));

Absolute scenes

You can add scenes anywhere in your tween's timeline by using tween.scene(). You just need to provide two of these parameters:

• begin (start time of the scene)
• duration (duration of the scene)
• end (end time of the scene)

final tween = MovieTween();

// start at 0ms and end at 1500ms
final scene1 = tween.scene(duration: const Duration(milliseconds: 1500));

// start at 200ms and end at 900ms
final scene2 = tween.scene(
  begin: const Duration(milliseconds: 200),
  duration: const Duration(milliseconds: 700),
);

// start at 700ms and end at 1400ms
final scene3 = tween.scene(
  begin: const Duration(milliseconds: 700),
  end: const Duration(milliseconds: 1400),
);

// start at 1000ms and end at 1600ms
final scene4 = tween.scene(
  duration: const Duration(milliseconds: 600),
  end: const Duration(milliseconds: 1600),
);

Relative scenes

You can also make scenes depend on each other by using thenFor().

final tween = MovieTween();

final firstScene = tween
    .scene(
      begin: const Duration(seconds: 0),
      duration: const Duration(seconds: 2),
    )
    .tween('x', ConstantTween<int>(0));

// secondScene references the firstScene
final secondScene = firstScene
    .thenFor(
      delay: const Duration(milliseconds: 200),
      duration: const Duration(seconds: 2),
    )
    .tween('x', ConstantTween<int>(1));

It is also possible to add an optional delay to add more time between scenes.

Overlapping scenes

Avoid overlapping tweens for the same property unless you intentionally want the earlier matching scene to keep control until it ends. Overlaps are supported, but non-overlapping scenes are usually easier to reason about and maintain.

Hint on code style

By using builder-style Dart syntax and comments, you can easily create a readable animation.

MovieTween()
    /// fade in
    .scene(
      begin: const Duration(seconds: 0),
      duration: const Duration(milliseconds: 300),
    )
    .tween('x', Tween<double>(begin: 0.0, end: 100.0))
    .tween('y', Tween<double>(begin: 0.0, end: 200.0))
    /// grow
    .thenFor(duration: const Duration(milliseconds: 700))
    .tween('x', Tween<double>(begin: 100.0, end: 200.0))
    .tween('y', Tween<double>(begin: 200.0, end: 400.0))
    /// fade out
    .thenFor(duration: const Duration(milliseconds: 300))
    .tween('x', Tween<double>(begin: 200.0, end: 0.0))
    .tween('y', Tween<double>(begin: 400.0, end: 0.0));

Animate properties

You can use tween() to specify a tween for a single property.

final tween = MovieTween();
final scene = tween.scene(end: const Duration(seconds: 1));

scene.tween('width', Tween(begin: 0.0, end: 100.0));
scene.tween('color', ColorTween(begin: Colors.red, end: Colors.blue));

You can fine-tune the timing with shiftBegin or shiftEnd for each property.

scene.tween(
  'width',
  Tween(begin: 0.0, end: 100.0),
  shiftBegin: const Duration(milliseconds: 200), // start later
  shiftEnd: const Duration(milliseconds: -200), // end earlier
);

Curves

You can customize the default easing curve on the MovieTween, scene, or property tween level.

final tween = MovieTween(curve: Curves.easeIn);

// scene1 will use Curves.easeIn defined by the MovieTween
final scene1 = tween.scene(duration: const Duration(seconds: 1));

// scene2 will use Curves.easeOut
final scene2 = tween.scene(
  duration: const Duration(seconds: 1),
  curve: Curves.easeOut,
);

// will use Curves.easeIn defined by the MovieTween
scene1.tween('value1', Tween(begin: 0.0, end: 100.0));

// will use Curves.easeOut defined by scene2
scene2.tween('value2', Tween(begin: 0.0, end: 100.0));

// will use Curves.easeInOut defined by property tween
scene2.tween(
  'value3',
  Tween(begin: 0.0, end: 100.0),
  curve: Curves.easeInOut,
);

Extrapolation

All values that are not explicitly set in the timeline will be extrapolated per property. Before the first tween of a property, MovieTween uses that property's first value. After the last tween of a property, it keeps that property's last value.

Only properties that are part of the MovieTween can be read from the resulting Movie. Accessing a property that was never tweened is an error.

final tween = MovieTween()
  // implicitly use 100.0 for width values from 0.0s - 1.0s
  // 1.0s - 2.0s
  ..scene(
    begin: const Duration(seconds: 1),
    duration: const Duration(seconds: 1),
  ).tween('width', Tween<double>(begin: 100.0, end: 200.0))
  // implicitly use 200.0 for width values from 2.0s - 3.0s
  // 3.0s - 4.0s
  ..scene(
    begin: const Duration(seconds: 3),
    end: const Duration(seconds: 4),
  ).tween('height', Tween<double>(begin: 400.0, end: 500.0));

Use developer tools

Creating complex tweens with multiple or staggered properties can be time-consuming to create and maintain. Use the Animation Developer Tools to streamline this process.

Animation duration

Normally, an Animatable or Tween doesn't contain duration information. The MovieTween class has a duration property that stores the total duration of the animation.

@override
Widget build(BuildContext context) {
  final tween = MovieTween()
    ..tween(
      'width',
      Tween<double>(begin: 0.0, end: 100.0),
      duration: const Duration(milliseconds: 700),
    )
    ..tween(
      'height',
      Tween<double>(begin: 300.0, end: 200.0),
      duration: const Duration(milliseconds: 700),
    );

  return PlayAnimationBuilder<Movie>(
    tween: tween,
    duration: tween.duration, // use duration from MovieTween
    builder: (context, value, _) {
      return Container(
        width: value.get('width'),
        height: value.get('height'),
        color: Colors.yellow,
      );
    },
  );
}

Hint: You can also multiply the duration value with a numeric factor in order to speed up or slow down an animation.

Of course, you can also use your own Duration for the animation.

Animation Mixin

AnimationMixin reduces boilerplate code when using AnimationController instances.

Basic usage pattern

Create an AnimationController by adding AnimationMixin to your stateful widget:

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

class MyAnimatedWidget extends StatefulWidget {
  const MyAnimatedWidget({super.key});

  @override
  _MyAnimatedWidgetState createState() => _MyAnimatedWidgetState();
}

// Add AnimationMixin to state class
class _MyAnimatedWidgetState extends State<MyAnimatedWidget>
    with AnimationMixin {
  late Animation<double> size;

  @override
  void initState() {
    size = Tween<double>(begin: 0.0, end: 200.0).animate(controller);
    controller.play();
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Container(width: size.value, height: size.value, color: Colors.red);
  }
}

💪 The AnimationMixin generates a preconfigured AnimationController as controller. You can use it directly. No need to worry about initialization or disposal.

The managed controllers automatically call setState() while they animate, so you can read animation values directly inside build().

Create multiple AnimationController instances

With multiple AnimationController instances, you can have many parallel animations at the same time.

AnimationMixin adds createController() to your state class, allowing you to create multiple managed AnimationController instances. ("Managed" means that you don't need to handle initialization or disposal.)

Create a managed AnimationController

First, create a class variable of type AnimationController. Then call createController() inside the initState() {...} method. That's all.

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

class MyAnimatedWidget extends StatefulWidget {
  const MyAnimatedWidget({super.key});

  @override
  _MyAnimatedWidgetState createState() => _MyAnimatedWidgetState();
}

// use AnimationMixin
class _MyAnimatedWidgetState extends State<MyAnimatedWidget>
    with AnimationMixin {
  late AnimationController sizeController; // declare custom AnimationController
  late Animation<double> size;

  @override
  void initState() {
    sizeController = createController(); // create custom AnimationController
    size = Tween<double>(begin: 0.0, end: 200.0).animate(sizeController);
    sizeController.play(duration: const Duration(seconds: 5));
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Container(width: size.value, height: size.value, color: Colors.red);
  }
}

Create many managed AnimationController instances

Create as many managed AnimationController instances as needed. AnimationMixin tracks and disposes them for you.

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

class MyAnimatedWidget extends StatefulWidget {
  const MyAnimatedWidget({super.key});

  @override
  _MyAnimatedWidgetState createState() => _MyAnimatedWidgetState();
}

class _MyAnimatedWidgetState extends State<MyAnimatedWidget>
    with AnimationMixin {
  late AnimationController widthController;
  late AnimationController heightController;
  late AnimationController colorController;

  late Animation<double> width;
  late Animation<double> height;
  late Animation<Color?> color;

  @override
  void initState() {
    widthController = createController()
      ..mirror(duration: const Duration(seconds: 5));
    heightController = createController()
      ..mirror(duration: const Duration(seconds: 3));
    colorController = createController()
      ..mirror(duration: const Duration(milliseconds: 1500));

    width = Tween<double>(begin: 100.0, end: 200.0).animate(widthController);
    height = Tween<double>(begin: 100.0, end: 200.0).animate(heightController);
    color = ColorTween(
      begin: Colors.red,
      end: Colors.blue,
    ).animate(colorController);

    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Container(
      width: width.value,
      height: height.value,
      color: color.value,
    );
  }
}

Advanced controller options

Use createController(fps: 30) to limit rebuilds for expensive animations. Use createController(unbounded: true) when you need an AnimationController.unbounded, for example for physics-style animations that can move beyond the default 0.0 to 1.0 range.

Shortcuts for AnimationController

The extension for AnimationController adds four convenience methods:

• controller.play() plays the animation and stops at the end.

• controller.playReverse() plays the animation in reverse and stops at the start.

• controller.loop() repeatedly plays the animation from the start to the end.

• controller.mirror() repeatedly plays the animation forward, then backwards, then forward again, and so on.

Each of these methods takes an optional duration named parameter to configure your animation action in one line of code.

Passing duration updates the controller's duration property. Future playback calls will keep using that value until you change it again.

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

void someFunction(AnimationController controller) {
  controller.play(duration: const Duration(milliseconds: 1500));
  controller.playReverse(duration: const Duration(milliseconds: 1500));
  controller.loop(duration: const Duration(milliseconds: 1500));
  controller.mirror(duration: const Duration(milliseconds: 1500));
}

You can use these methods alongside the existing controller.stop() and controller.reset() methods.

Animation Developer Tools

The Animation Developer Tools allow you to create or review your animation step by step.

Basic usage pattern

Wrap your UI with the AnimationDeveloperTools widget.

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

class MyPage extends StatelessWidget {
  const MyPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      // place DevTools high in the widget hierarchy
      body: AnimationDeveloperTools(
        child: Container(), // your UI
      ),
    );
  }
}

Enable developer mode on the animation you want to debug.

The toolbar can be placed at the top, bottom, or hidden with the position parameter:

AnimationDeveloperTools(
  position: AnimationDeveloperToolsPosition.bottom,
  child: Container(),
)

Using Animation Builder widgets

The Animation Builder widgets

• PlayAnimationBuilder
• LoopAnimationBuilder
• MirrorAnimationBuilder
• CustomAnimationBuilder

have a constructor parameter developerMode that can be set to true. It will connect to the closest AnimationDeveloperTools widget.

With developerMode enabled, the developer toolbar drives the animation. The widget's normal playback instruction, such as control or delay, is not applied while debugging.

Example

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

void main() => runApp(const MaterialApp(home: Scaffold(body: MyPage())));

class MyPage extends StatelessWidget {
  const MyPage({super.key});

  @override
  Widget build(BuildContext context) {
    return SafeArea(
      // place DevTools high in the widget hierarchy
      child: AnimationDeveloperTools(
        child: Center(
          child: PlayAnimationBuilder<double>(
            tween: Tween<double>(begin: 0.0, end: 100.0),
            duration: const Duration(seconds: 1),
            developerMode: true, // enable developer mode
            builder: (context, value, child) {
              return Container(width: value, height: value, color: Colors.blue);
            },
          ),
        ),
      ),
    );
  }
}

Using Animation Mixin

If your stateful widget uses AnimationMixin to manage your AnimationController instances, you can call enableDeveloperMode() to connect to the closest AnimationDeveloperTools widget.

Example

import 'package:flutter/material.dart';
import 'package:simple_animations/simple_animations.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: Scaffold(
        body: SafeArea(
          // place DevTools high in the widget hierarchy
          child: AnimationDeveloperTools(child: Center(child: MyAnimation())),
        ),
      ),
    );
  }
}

class MyAnimation extends StatefulWidget {
  const MyAnimation({super.key});

  @override
  _MyAnimationState createState() => _MyAnimationState();
}

class _MyAnimationState extends State<MyAnimation> with AnimationMixin {
  late Animation<double> size;

  @override
  void initState() {
    size = Tween<double>(begin: 0.0, end: 100.0).animate(controller);
    enableDeveloperMode(controller); // enable developer mode
    controller.forward();
    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Container(width: size.value, height: size.value, color: Colors.blue);
  }
}

Features and tricks

The Animation Developer Tools come with several features that simplify your development workflow:

• Regardless of the real animation, with developer mode activated, the animation will always loop.
• You can use Flutter hot reloading for editing and debugging if your tween is created stateless.
• Use the slider to edit the animated scene while paused.
• You can slow down the animation to inspect specific details.
• Use the interval buttons to focus on a time span of the animation.