Implementing Flutter Animations

Contents

• Core Concepts
• Animation Strategies
• Workflows
• Implementing Implicit Animations
• Implementing Explicit Animations
• Implementing Hero Transitions
• Implementing Physics-Based Animations
• Examples

Core Concepts

Manage Flutter animations using the core typed Animation system. Do not manually calculate frames; rely on the framework's ticker and interpolation classes.

• Animation<T>: Treat this as an abstract representation of a value that changes over time. It holds state

(completed, dismissed) and notifies listeners, but knows nothing about the UI.

• AnimationController: Instantiate this to drive the animation. It generates values (typically 0.0 to 1.0) tied to

the screen refresh rate. Always provide a vsync (usually via SingleTickerProviderStateMixin) to prevent offscreen resource consumption. Always dispose() controllers to prevent memory leaks.

• Tween<T>: Define a stateless mapping from an input range (usually 0.0-1.0) to an output type (e.g., Color,

Offset, double). Chain tweens with curves using .animate().

• Curve: Apply non-linear timing (e.g., Curves.easeIn, Curves.bounceOut) to an animation using a

CurvedAnimation or CurveTween.

Animation Strategies

Apply conditional logic to select the correct animation approach:

• If animating simple property changes (size, color, opacity) without playback control: Use Implicit Animations (e.g.,

AnimatedContainer, AnimatedOpacity, TweenAnimationBuilder).

• If requiring playback control (play, pause, reverse, loop) or coordinating multiple properties: Use Explicit

Animations (e.g., AnimationController with AnimatedBuilder or AnimatedWidget).

• If animating elements between two distinct routes: Use Hero Animations (Shared Element Transitions).
• If modeling real-world motion (e.g., snapping back after a drag): Use Physics-Based Animations (e.g.,

SpringSimulation).

• If animating a sequence of overlapping or delayed motions: Use Staggered Animations (multiple Tweens driven by a

single AnimationController using Interval curves).

Workflows

#### Implementing Implicit Animations

Use this workflow for "fire-and-forget" state-driven animations.

• [ ] Task Progress:
• [ ] Identify the target properties to animate (e.g., width, color).
• [ ] Replace the static widget (e.g., Container) with its animated counterpart (e.g., AnimatedContainer).
• [ ] Define the duration property.
• [ ] (Optional) Define the curve property for non-linear motion.
• [ ] Trigger the animation by updating the properties inside a setState() call.
• [ ] Run validator -> review UI for jank -> adjust duration/curve if necessary.

#### Implementing Explicit Animations

Use this workflow when you need granular control over the animation lifecycle.

• [ ] Task Progress:
• [ ] Add SingleTickerProviderStateMixin (or TickerProviderStateMixin for multiple controllers) to the State

class.

• [ ] Initialize an AnimationController in initState(), providing vsync: this and a duration.
• [ ] Define a Tween and chain it to the controller using .animate().
• [ ] Wrap the target UI in an AnimatedBuilder (preferred for complex trees) or subclass AnimatedWidget.
• [ ] Pass the Animation object to the AnimatedBuilder's animation property.
• [ ] Control playback using controller.forward(), controller.reverse(), or controller.repeat().
• [ ] Call controller.dispose() in the dispose() method.
• [ ] Run validator -> check for memory leaks -> ensure dispose() is called.

#### Implementing Hero Transitions

Use this workflow to fly a widget between two routes.

• [ ] Task Progress:
• [ ] Wrap the source widget in a Hero widget.
• [ ] Assign a unique, data-driven tag to the source Hero.
• [ ] Wrap the destination widget in a Hero widget.
• [ ] Assign the exact same tag to the destination Hero.
• [ ] Ensure the widget trees inside both Hero widgets are visually similar to prevent jarring jumps.
• [ ] Trigger the transition by pushing the destination route via Navigator.

#### Implementing Physics-Based Animations

Use this workflow for gesture-driven, natural motion.

• [ ] Task Progress:
• [ ] Set up an AnimationController (do not set a fixed duration).
• [ ] Capture gesture velocity using a GestureDetector (e.g., onPanEnd providing DragEndDetails).
• [ ] Convert the pixel velocity to the coordinate space of the animating property.
• [ ] Instantiate a SpringSimulation with mass, stiffness, damping, and the calculated velocity.
• [ ] Drive the controller using controller.animateWith(simulation).

Examples

<details> <summary><b>Example: Explicit Animation (Staggered with AnimatedBuilder)</b></summary>

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

  @override
  State<StaggeredAnimationDemo> createState() => _StaggeredAnimationDemoState();
}

class _StaggeredAnimationDemoState extends State<StaggeredAnimationDemo> with SingleTickerProviderStateMixin {
  late AnimationController _controller;
  late Animation<double> _widthAnimation;
  late Animation<Color?> _colorAnimation;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(
      duration: const Duration(seconds: 2),
      vsync: this,
    );

    // Staggered width animation (0.0 to 0.5 interval)
    _widthAnimation = Tween<double>(begin: 50.0, end: 200.0).animate(
      CurvedAnimation(
        parent: _controller,
        curve: const Interval(0.0, 0.5, curve: Curves.easeIn),
      ),
    );

    // Staggered color animation (0.5 to 1.0 interval)
    _colorAnimation = ColorTween(begin: Colors.blue, end: Colors.red).animate(
      CurvedAnimation(
        parent: _controller,
        curve: const Interval(0.5, 1.0, curve: Curves.easeOut),
      ),
    );

    _controller.forward();
  }

  @override
  void dispose() {
    _controller.dispose(); // CRITICAL: Prevent memory leaks
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return AnimatedBuilder(
      animation: _controller,
      builder: (context, child) {
        return Container(
          width: _widthAnimation.value,
          height: 50.0,
          color: _colorAnimation.value,
        );
      },
    );
  }
}

</details>

<details> <summary><b>Example: Custom Page Route Transition</b></summary>

Route createCustomRoute(Widget destination) {
  return PageRouteBuilder(
    pageBuilder: (context, animation, secondaryAnimation) => destination,
    transitionsBuilder: (context, animation, secondaryAnimation, child) {
      const begin = Offset(0.0, 1.0); // Start from bottom
      const end = Offset.zero;
      const curve = Curves.easeOut;

      final tween = Tween(begin: begin, end: end).chain(CurveTween(curve: curve));
      final offsetAnimation = animation.drive(tween);

      return SlideTransition(
        position: offsetAnimation,
        child: child,
      );
    },
  );
}

// Usage: Navigator.of(context).push(createCustomRoute(const NextPage()));

</details>

Testing Animation-Driven State

In widget tests, never pumpAndSettle blindly when an animation never settles (e.g., a repeat() loop). Advance the clock explicitly with await tester.pump(duration) to step to a known frame, or await tester.pumpAndSettle() for finite animations, then assert the intermediate or final widget state. See the flutter-testing-apps skill.