Flutter Animations

Overview

Create smooth, performant animations in Flutter using the right approach for each use case. This skill covers complete animation workflow: from choosing between implicit/explicit approaches to implementing complex effects like hero transitions and staggered animations.

Animation Type Decision Tree

Choose the right animation type based on your requirements:

Implicit Animations - Use when:

Animating a single property (color, size, position)
Animation is triggered by state change
No need for fine-grained control

Explicit Animations - Use when:

Need full control over animation lifecycle
Animating multiple properties simultaneously
Need to react to animation state changes
Creating custom animations or transitions

Hero Animations - Use when:

Sharing an element between two screens
Creating shared element transitions
User expects element to "fly" between routes

Staggered Animations - Use when:

Multiple animations should run sequentially or overlap
Creating ripple effects or sequential reveals
Animating list items in sequence

Physics-Based Animations - Use when:

Animations should feel natural/physical
Spring-like behavior, scrolling gestures
Draggable interactions

Implicit Animations

Implicit animations automatically handle the animation when properties change. No controller needed.

Common Implicit Widgets

AnimatedContainer - Animates multiple properties (size, color, decoration, padding):

dart

AnimatedContainer(
  duration: const Duration(milliseconds: 300),
  curve: Curves.easeInOut,
  width: _expanded ? 200 : 100,
  height: _expanded ? 200 : 100,
  color: _expanded ? Colors.blue : Colors.red,
  child: const FlutterLogo(),
)

AnimatedOpacity - Simple fade animation:

dart

AnimatedOpacity(
  opacity: _visible ? 1.0 : 0.0,
  duration: const Duration(milliseconds: 300),
  child: const Text('Hello'),
)

TweenAnimationBuilder - Custom tween animation without boilerplate:

dart

TweenAnimationBuilder<double>(
  tween: Tween<double>(begin: 0, end: 1),
  duration: const Duration(seconds: 1),
  builder: (context, value, child) {
    return Opacity(
      opacity: value,
      child: Transform.scale(
        scale: value,
        child: child,
      ),
    );
  },
  child: const FlutterLogo(),
)

Other implicit widgets:

```
AnimatedPadding
```
- Padding animation
```
AnimatedPositioned
```
- Position animation (in Stack)
```
AnimatedAlign
```
- Alignment animation
```
AnimatedContainer
```
- Multiple properties
```
AnimatedSwitcher
```
- Cross-fade between widgets
```
AnimatedDefaultTextStyle
```
- Text style animation

Best Practices

Prefer implicit animations for simple cases
Use appropriate curves for natural motion (see
```
Curves
```
class)
Set
```
curve
```
and
```
duration
```
for predictable behavior
Use
```
onEnd
```
callback when needed
Avoid nested implicit animations for performance

Explicit Animations

Explicit animations provide full control with AnimationController.

Core Components

AnimationController - Drives the animation:

dart

late AnimationController _controller;

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

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

Tween - Interpolates between begin and end values:

dart

animation = Tween<double>(begin: 0, end: 300).animate(_controller);

CurvedAnimation - Applies a curve to the animation:

dart

animation = CurvedAnimation(
  parent: _controller,
  curve: Curves.easeInOut,
);

AnimatedWidget Pattern

Best for reusable animated widgets:

dart

class AnimatedLogo extends AnimatedWidget {
  const AnimatedLogo({super.key, required Animation<double> animation})
    : super(listenable: animation);

  @override
  Widget build(BuildContext context) {
    final animation = listenable as Animation<double>;
    return Center(
      child: Container(
        height: animation.value,
        width: animation.value,
        child: const FlutterLogo(),
      ),
    );
  }
}

AnimatedBuilder Pattern

Best for complex widgets with animations:

dart

class GrowTransition extends StatelessWidget {
  const GrowTransition({
    required this.child,
    required this.animation,
    super.key,
  });

  final Widget child;
  final Animation<double> animation;

  @override
  Widget build(BuildContext context) {
    return Center(
      child: AnimatedBuilder(
        animation: animation,
        builder: (context, child) {
          return SizedBox(
            height: animation.value,
            width: animation.value,
            child: child,
          );
        },
        child: child,
      ),
    );
  }
}

Monitoring Animation State

dart

animation.addStatusListener((status) {
  switch (status) {
    case AnimationStatus.completed:
      _controller.reverse();
      break;
    case AnimationStatus.dismissed:
      _controller.forward();
      break;
    default:
      break;
  }
});

Multiple Simultaneous Animations

dart

class AnimatedLogo extends AnimatedWidget {
  const AnimatedLogo({super.key, required Animation<double> animation})
    : super(listenable: animation);

  static final _opacityTween = Tween<double>(begin: 0.1, end: 1);
  static final _sizeTween = Tween<double>(begin: 0, end: 300);

  @override
  Widget build(BuildContext context) {
    final animation = listenable as Animation<double>;
    return Center(
      child: Opacity(
        opacity: _opacityTween.evaluate(animation),
        child: Container(
          height: _sizeTween.evaluate(animation),
          width: _sizeTween.evaluate(animation),
          child: const FlutterLogo(),
        ),
      ),
    );
  }
}

Built-in Explicit Transitions

Flutter provides ready-to-use transitions:

```
FadeTransition
```
- Fade animation
```
ScaleTransition
```
- Scale animation
```
SlideTransition
```
- Slide animation
```
SizeTransition
```
- Size animation
```
RotationTransition
```
- Rotation animation
```
PositionedTransition
```
- Position animation (in Stack)

Example:

dart

FadeTransition(
  opacity: _animation,
  child: const FlutterLogo(),
)

Performance Tips

Dispose controllers when widget is removed
Use
```
AnimatedBuilder
```
for optimal rebuilds
Avoid
```
setState()
```
in animation listeners (use
```
AnimatedWidget
```
/
```
AnimatedBuilder
```
)
Use
```
timeDilation
```
to slow animations during debugging

Hero Animations

Hero animations create shared element transitions between screens.

Basic Hero Animation

Source screen:

dart

Hero(
  tag: 'hero-image',
  child: Image.asset('images/logo.png'),
)

Destination screen:

dart

Hero(
  tag: 'hero-image',  // Same tag!
  child: Image.asset('images/logo.png'),
)

Complete Example

dart

class PhotoHero extends StatelessWidget {
  const PhotoHero({
    super.key,
    required this.photo,
    this.onTap,
    required this.width,
  });

  final String photo;
  final VoidCallback? onTap;
  final double width;

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: width,
      child: Hero(
        tag: photo,
        child: Material(
          color: Colors.transparent,
          child: InkWell(
            onTap: onTap,
            child: Image.asset(photo, fit: BoxFit.contain),
          ),
        ),
      ),
    );
  }
}

Navigating between screens:

dart

Navigator.of(context).push(
  MaterialPageRoute<void>(
    builder: (context) {
      return Scaffold(
        appBar: AppBar(title: const Text('Detail')),
        body: Center(
          child: PhotoHero(
            photo: 'images/logo.png',
            width: 300.0,
            onTap: () => Navigator.of(context).pop(),
          ),
        ),
      );
    },
  ),
);

Radial Hero Animation

Transform from circle to rectangle during transition:

dart

class RadialExpansion extends StatelessWidget {
  const RadialExpansion({
    super.key,
    required this.maxRadius,
    this.child,
  }) : clipRectSize = 2.0 * (maxRadius / math.sqrt2);

  final double maxRadius;
  final double clipRectSize;
  final Widget? child;

  @override
  Widget build(BuildContext context) {
    return ClipOval(
      child: Center(
        child: SizedBox(
          width: clipRectSize,
          height: clipRectSize,
          child: ClipRect(child: child),
        ),
      ),
    );
  }
}

Use with

MaterialRectCenterArcTween

for center-based interpolation:

dart

static RectTween _createRectTween(Rect? begin, Rect? end) {
  return MaterialRectCenterArcTween(begin: begin, end: end);
}

Hero Best Practices

Use unique, consistent tags (often the data object itself)
Keep hero widget trees similar between routes
Wrap images in
```
Material
```
with transparent color for "pop" effect
Use
```
timeDilation
```
to debug transitions
Consider
```
HeroMode
```
to disable hero animations when needed

Staggered Animations

Run multiple animations with different timing.

Basic Staggered Animation

All animations share one controller:

dart

class StaggerAnimation extends StatelessWidget {
  StaggerAnimation({super.key, required this.controller})
    : opacity = Tween<double>(begin: 0.0, end: 1.0).animate(
        CurvedAnimation(
          parent: controller,
          curve: const Interval(0.0, 0.100, curve: Curves.ease),
        ),
      ),
      width = Tween<double>(begin: 50.0, end: 150.0).animate(
        CurvedAnimation(
          parent: controller,
          curve: const Interval(0.125, 0.250, curve: Curves.ease),
        ),
      );

  final AnimationController controller;
  final Animation<double> opacity;
  final Animation<double> width;

  Widget _buildAnimation(BuildContext context, Widget? child) {
    return Container(
      alignment: Alignment.bottomCenter,
      child: Opacity(
        opacity: opacity.value,
        child: Container(
          width: width.value,
          height: 150,
          color: Colors.blue,
        ),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return AnimatedBuilder(
      animation: controller,
      builder: _buildAnimation,
    );
  }
}

Interval-Based Timing

Each animation has an Interval between 0.0 and 1.0:

dart

animation = Tween<double>(begin: 0, end: 300).animate(
  CurvedAnimation(
    parent: controller,
    curve: const Interval(
      0.25,  // Start at 25% of controller duration
      0.50,  // End at 50% of controller duration
      curve: Curves.ease,
    ),
  ),
);

Common Tweens

dart

borderRadius = BorderRadiusTween(
  begin: BorderRadius.circular(4),
  end: BorderRadius.circular(75),
).animate(
  CurvedAnimation(
    parent: controller,
    curve: const Interval(0.375, 0.500, curve: Curves.ease),
  ),
);

Staggered Menu Animation

dart

class _MenuState extends State<Menu> with SingleTickerProviderStateMixin {
  static const _initialDelayTime = Duration(milliseconds: 50);
  static const _itemSlideTime = Duration(milliseconds: 250);
  static const _staggerTime = Duration(milliseconds: 50);
  static const _buttonDelayTime = Duration(milliseconds: 150);
  static const _buttonTime = Duration(milliseconds: 500);

  final _animationDuration =
      _initialDelayTime +
      (_staggerTime * _menuTitles.length) +
      _buttonDelayTime +
      _buttonTime;

  late AnimationController _controller;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(
      duration: _animationDuration,
      vsync: this,
    );
    _controller.forward();
  }

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

Stagger Best Practices

Use
```
Interval
```
to offset animations in time
Ensure controller duration covers all intervals
Use curves for natural motion within intervals
Consider
```
timeDilation
```
to debug timing
Stagger menu items with increasing delay for ripple effect

Physics-Based Animations

Create natural-feeling animations using physics simulations.

Fling Animation

dart

_controller.fling(
  velocity: 2.0,  // Units per second
);

Custom Physics Simulation

dart

_controller.animateWith(
  SpringSimulation(
    spring: const SpringDescription(
      mass: 1,
      stiffness: 100,
      damping: 10,
    ),
    start: 0.0,
    end: 1.0,
    velocity: 0.0,
  ),
);

Common Physics Simulations

```
SpringSimulation
```
- Spring physics
```
BouncingScrollSimulation
```
- Scroll with bounce
```
ClampingScrollSimulation
```
- Scroll without bounce
```
GravitySimulation
```
- Gravity-based

Best Practices

DO

Dispose AnimationController in widget disposal
Use
```
AnimatedBuilder
```
/
```
AnimatedWidget
```
instead of
```
setState()
```
in listeners
Choose appropriate curves for natural motion
Use
```
timeDilation
```
for debugging animations
Consider performance (avoid heavy widgets in animation builds)
Test animations on various devices
Support reverse animations for intuitive feel

DON'T

Forget to dispose AnimationController (memory leak)
Use
```
setState()
```
in animation listeners when
```
AnimatedBuilder
```
suffices
Assume animation completes instantly (handle
```
AnimationStatus
```
)
Over-animate (animations can distract users)
Create animations that feel "jerky" (use smooth curves)
Ignore accessibility (respect
```
disableAnimations
```
preference)

Resources

references/

implicit.md - Complete reference for implicit animation widgets with examples and best practices.

explicit.md - Deep dive into explicit animations, AnimationController, and patterns.

hero.md - Hero animations guide with standard and radial transitions.

staggered.md - Staggered animation patterns and timing strategies.

physics.md - Physics-based animations and simulations.

curves.md - Reference for Curves class and choosing appropriate curves.

assets/templates/

Template code for common animation patterns:

```
implicit_animation.dart
```
- Implicit animation examples
```
explicit_animation.dart
```
- Explicit animation setup
```
hero_transition.dart
```
- Hero animation boilerplate
```
staggered_animation.dart
```
- Staggered animation template

flutter-animations

NPX Install

Tags

SKILL.md Content

Flutter Animations

Overview

Animation Type Decision Tree

Implicit Animations

Common Implicit Widgets

Best Practices

Explicit Animations

Core Components

AnimatedWidget Pattern

AnimatedBuilder Pattern

Monitoring Animation State

Multiple Simultaneous Animations

Built-in Explicit Transitions

Performance Tips

Hero Animations

Basic Hero Animation

Complete Example

Radial Hero Animation

Hero Best Practices

Staggered Animations

Basic Staggered Animation

Interval-Based Timing

Common Tweens

Staggered Menu Animation

Stagger Best Practices

Physics-Based Animations

Fling Animation

Custom Physics Simulation

Common Physics Simulations

Best Practices

DO

DON'T

Resources

references/

assets/templates/