A great example is AnimatedOpacity. This widget animates based on the value passed for opacity, and then fades its child in or out.

The code for using this is as follows:

AnimatedOpacity(
  opacity: opacityLevel,
  duration: const Duration(seconds: 3),
  child: const FlutterLogo(),
)

All that needs doing to change the opacity is to pass in a different opacityLevel - no need to know how animations, tweens, or any other advanced concepts work.

This is extremely useful if you want to do something provided by flutter - examples include AnimatedOpacity, AnimatedPositioned, AnimatedSize . There are even more multipurpose widgets such as AnimatedCrossFade and AnimatedWidget that will transition between two widgets or any widget passed in respectively. But what if you want to do something else?

This post is going to assume some knowledge of how the flutter animation framework works, or at least animations in general. Without that knowledge you should be able to get things to work anyways, but it's worth knowing what a Tween and Animation are and the difference between them. I'm not going to explain here as that's already covered in their documentation, but give that a read before continuing if you're unsure.

Writing your ImplicitlyAnimatedWidget subclass

The first thing you'll want to do is create new classes subclassing ImplicitlyAnimatedWidgetand ImplicitlyAnimatedWidgetState. For this example, we're going to create a widget that flips its child vertically.

class AnimatedFlipY extends ImplicitlyAnimatedWidget {
  const AnimatedFlipY({
    super.key,
    required this.child,
    required this.flipped,
    required super.duration,
  });

  final Widget child;
  final bool flipped;

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

class _AnimatedFlipYState extends ImplicitlyAnimatedWidgetState<AnimatedFlipY> {
  @override
  void forEachTween(TweenVisitor<dynamic> visitor) {}

  @override
  void didUpdateTweens() {}

  @override
  Widget build(BuildContext context) {}
}

In the above example, you'll notice that the AnimatedFlipY class overrides the createState method to create an instance of _AnimatedFlipYState, which implements ImplicitlyAnimatedWidgetState<AnimatedFlipY> . If you've written a StatefulWidget subclass, this will be very familiar, but ImplicitlyAnimatedWidgetState introduces forEachTween which needs to be implemented in addition to the build method. We'll also need to override didUpdateTweens.

In the forEachTween method, we need to use the visitor to create a tween object which we will use to perform the animation. This is the implementation:

Tween<double>? _flipY;

@override
void forEachTween(TweenVisitor<dynamic> visitor) {
  _flipY = visitor(
    _flipY,
    widget.flipped ? 1.0 : 0.0,
    (dynamic value) => Tween<double>(begin: value as double),
  ) as Tween<double>;
}

What we're doing here is calling the TweenVisitor with the current tween, the value we want to animate towards, and a builder function which creates a new tween given the input value. The result of this is a tween with the current value as the beginning and the target value (1.0 or 0.0 depending on whether we want the object to be flipped or not) as the end. There's a couple peculiarities in this code that should be mentioned - TweenVisitor's type is dynamic because the Tween we're creating can be of any type, not just double, and might even be used for multiple types; and we have to use an optional for _flipY because it is null the first time this method is called.

Next let's look at the didUpdateTweens method. This gets called after the object is first constructed and after a change to the parameters passed to the AnimatedFlipY widget.

late Animation<double> _flipAnimation;

@override
void didUpdateTweens() {
  _flipAnimation = animation.drive(_flipY!);
}

In this case, we can use a late modifier rather than optional for _flipAnimation as it will never be accessed until after it is set. The animation object is something managed by the ImplicitlyAnimatedWidgetState, and by calling drive on it with _flipY we are creating a new animation that will animated to the correct values.

If we simply used the animation object, it would always animate from 0.0 to 1.0 as that is all the superclass knows about, which is not what we want - let's say that our animation is at 0.6 and then we set flipped to false - we then want our animation to run from 0.6 to 0.0. By creating the new Animation object and assigning it to _flipAnimation we are able to control the output of our animation.

Now take a look at the build method of our class:

@override
Widget build(BuildContext context) {
  return AnimatedBuilder(
    animation: _flipAnimation,
    builder: (context, child) {
      final flipMatrix = Matrix4.rotationX(_flipAnimation.value * pi);
      return Transform(
        transform: flipMatrix,
        alignment: Alignment.center,
        child: child,
      );
    },
    child: widget.child,
  );
}

Whew, that's a big one. Let's take a look at what is going on part by part:

AnimatedBuilder(
  animation: _flipAnimation,
  builder: (context, child) {
    ...
  },
  child: widget.child,
);

This or something like it will need to be done for any implementation of an implicitly animated widget so that the animation is actually listened to. Another way of doing it will be shown at the end of this post.

We are using an AnimatedBuilder and passing the _flipAnimation animation to it. The AnimatedBuilder will listen to the animation and call the builder function every time the animation is changed; this means that the amount of work done in the builder function should be minimized as it is performed many times. If there are any static elements to the animation you're creating, those should be passed into the child parameter - in our case, the widget to be flipped. This child will then be passed into the builder function to be used there.

Finally, here is the code for doing the actual flip:

    final flipMatrix = Matrix4.rotationX(_flipAnimation.value * pi);
    return Transform(
    transform: flipMatrix,
      origin: Offset(0, flipAxis),
      alignment: Alignment.center,
      child: child,
    );

This uses a matrix calculation to calculate the amount of rotation around X axis and sets the alignment of the transform to the center so that the axis of rotation is in the middle of the object.

All of this results in the following:

class AnimatedFlipY extends ImplicitlyAnimatedWidget {
  const AnimatedFlipY({
    super.key,
    required this.child,
    required this.flipped,
    required super.duration,
  });

  final Widget child;
  final bool flipped;

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

class _AnimatedFlipYState extends ImplicitlyAnimatedWidgetState<AnimatedFlipY> {
  Tween<double>? _flipY;

  @override
  void forEachTween(TweenVisitor<dynamic> visitor) {
    _flipY =
        visitor(
              _flipY,
              widget.flipped ? 1.0 : 0.0,
              (dynamic value) => Tween<double>(begin: value as double),
            )
            as Tween<double>;
  }

  late Animation<double> _flipAnimation;

  @override
  void didUpdateTweens() {
    _flipAnimation = animation.drive(_flipY!);
  }

  @override
  Widget build(BuildContext context) {
    return AnimatedBuilder(
      animation: _flipAnimation,
      builder: (context, child) {
        final flipMatrix = Matrix4.rotationX(_flipAnimation.value * pi);
        return Transform(
          transform: flipMatrix,
          alignment: Alignment.center,
          child: child,
        );
      },
      child: widget.child,
    );
  }
}

With that, you should be able to write your own implicitly animated widgets!

See in dartpad here.

Bonus:

I mentioned that there is an alternative way to use the animation. If you're going to be using the vertical flip (or whatever you're writing) in other places, you might want to make this into its own widget. That way you can re-use the logic elsewhere, like in a page transition for example. Yay for reusability!

The convention within the flutter codebase seems to be to name these types of objects ...Transition, so we're going to call our widget FlipYTransition. This would be used in the above example instead of the AnimatedBuilder, and does essentially the same thing.

class FlipYTransition extends AnimatedWidget {
  const FlipYTransition({
    super.key,
    required Animation<double> flip,
    this.child,
  }) : super(listenable: flip);

  final Widget? child;

  Animation<double> get flip => listenable as Animation<double>;

  @override
  Widget build(BuildContext context) {
    final flipMatrix = Matrix4.rotationX(flip.value * pi);
    return Transform(
      transform: flipMatrix,
      alignment: Alignment.center,
      child: child,
    );
  }
}

Everything done here should be relatively easy to follow from the previous example with the exception of the flip getter - this is not really necessary but provides a cleaner way to access the flip animation which was passed in, as the AnimatedWidget widget only saves the animation as a Listenable.

The problem...

... is that I need to draw dots between the beginning and end of a row. This row can be of any length, but dots need to be spaced evenly and to fill the full space between the start and finish:

The work...

The easiest way to do this is to use a custom painter. What we need to do is figure out where the dots should be drawn in relation to the width and height of the box given to the custom painter to paint. Because of the way that circles are drawn in Flutter, I need to calculate everything based on the centre of the points. For now, that looks like this:

final offset = radius + spacing + radius;
final vPos = size.height / 2;
var hPos = radius;

To do the actual drawing, I'll be subclassing CustomPainter and using a CustomPaint; if you haven't run across those yet I recommend taking a look at the documentation. To do the drawing, I will be using the canvas and size parameters passed to the paint function of the CustomPainter subclass.

I need to draw each of the points, then move to the next, while ensuring that I don't go past the right of the box given to us to draw in. I also create a Paint object loaded up with whichever colour I want to draw the dots with. For this implementation I've drawn the points from the left of the available space towards the right until the end of the available space. This is what the code to do that looks like:

final paint = Paint()..color = color;
do {
  canvas.drawCircle(Offset(hPos, vPos), radius, paint);
  hPos += offset;
} while (hPos + radius <= width);

This all needs to be set up in a CustomPainter, and then passed to a CustomPaint; here's the bare basic setup but made configurable:

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return CustomPaint(painter: DotsPainter())
  }
}

class DotsPainter extends CustomPainter {
  final double radius;
  final Color color;
  final double spacing;

  const DotsPainter({
    required this.radius,
    required this.color,
    required this.spacing,
  });

  @override
  void paint(Canvas canvas, Size size) {
    final paint = Paint()..color = color;
    final width = size.width;
    final vPos = size.height / 2;
    final offset = radius + spacing + radius;

    var hPos = radius;
    do {
      canvas.drawCircle(Offset(hPos, vPos), radius, paint);
      hPos += offset;
    } while (hPos + radius <= width);
  }

  @override
  bool shouldRepaint(covariant DotsPainter oldDelegate) =>
      oldDelegate.spacing != spacing || oldDelegate.color != color || oldDelegate.radius != radius;
}

The shouldRepaint function has an implementation that will ensure that any changes to the radius/colour/spacing ensures the painter will redraw. This does everything needed to draw the example given at the start with the correct colouring & sizing.

The end result...

For a full example, tap the icon below. You can open the code used to generate this preview, which includes some extra set-up code and hardcodes the colours & sizes used.

This solves the problem to my satisfaction and recreates the example shown at the start. I've made use of the configurable colouring & sizing to make the dots show up better for the sake of this example.

However, as I keep building out the app I've realized something - drawing the points from the left isn't always sufficient. For example, if you have a list of items each with a different length of text on the left, the dots will be drawn according to that size which will result in them not matching up vertically. Sigh. I'll write a post soon showing how I've fixed that!