Skill v1.0.0

Automated scan100/100

madteacher/mad-agents-skills/flutter-animations

──Details

PublishedApril 27, 2026 at 04:13 PM

Content Hashsha256:4d40d458d9e6555c...

Git SHA69d260a36403

──Files

Files (1 file, 14.6 KB)

SKILL.md14.6 KBactive

SKILL.md · 607 lines · 14.6 KB

version: "1.0.0" name: flutter-animations description: "Comprehensive guide for implementing animations in Flutter. Use when adding motion and visual effects to Flutter apps: implicit animations (AnimatedContainer, AnimatedOpacity, TweenAnimationBuilder), explicit animations (AnimationController, Tween, AnimatedWidget/AnimatedBuilder), hero animations (shared element transitions), staggered animations (sequential/overlapping), and physics-based animations. Includes workflow for choosing the right animation type, implementation patterns, and best practices for performance and user experience." metadata: author: Stanislav [MADTeacher] Chernyshev version: "1.0"

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

All versions v1.0.1 →