home / skills / madteacher / mad-agents-skills / flutter-animations

flutter-animations skill

safe

This skill helps you implement Flutter animations effectively by choosing implicit, explicit, hero, staggered, and physics-based approaches for smooth UX.

npx playbooks add skill madteacher/mad-agents-skills --skill flutter-animations

Review the files below or copy the command above to add this skill to your agents.

Files (11)

SKILL.md

14.5 KB

---
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."
---

# 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

Overview

This skill is a comprehensive guide for implementing animations in Flutter, covering implicit and explicit approaches, hero and staggered transitions, and physics-based motion. It helps you choose the right animation type, implement common patterns, and apply performance and UX best practices. Use it to add motion that feels natural, accessible, and maintainable.

How this skill works

The guide inspects common animation needs (single-property changes, multi-property control, shared element transitions, sequential effects, and physics-driven behavior) and maps them to Flutter APIs and patterns. It explains when to use implicit widgets versus AnimationController-driven explicit animations, demonstrates AnimatedWidget/AnimatedBuilder patterns, shows hero and staggered setups, and covers physics simulations and timing strategies. Each topic includes implementation patterns and performance tips.

When to use it

Simple property changes like color, size, or opacity where minimal code is desired (implicit animations).
Complex sequences, synchronized multi-property animations, or when you need lifecycle control (explicit AnimationController).
Shared element transitions between routes (Hero animations) for visual continuity.
Sequential or overlapping effects for lists, menus, or reveal animations (staggered animations).
Natural, springy, or gesture-driven motion that requires physics simulations.

Best practices

Prefer implicit widgets for simple, single-property changes to reduce boilerplate.
Dispose AnimationController in dispose() to avoid leaks and use AnimatedBuilder/AnimatedWidget to minimize setState() usage.
Use Curves and Interval to create natural timing; tune durations for responsiveness and clarity.
Avoid animating heavy widgets; keep build methods lightweight and test on target devices.
Respect accessibility: detect and honor system reduce-motion preferences and avoid over-animating.

Example use cases

Fade and size changes with AnimatedOpacity/AnimatedContainer for responsive UI feedback.
A custom loader built with AnimationController, Tween, and AnimatedBuilder for controlled loops and states.
Showcase-detail transition using Hero to animate an image between list and detail routes.
Staggered menu where items slide and fade in sequence using a shared controller and Interval curves.
Drag-to-dismiss or fling interactions using SpringSimulation or controller.fling for natural motion.

FAQ

When should I choose implicit over explicit animations?

Use implicit animations when animating a single property triggered by a state change and you don’t need fine-grained control. Choose explicit animations when you need lifecycle control, multiple coordinated tweens, or custom timing.

How do I avoid performance problems during animations?

Dispose controllers, use AnimatedBuilder/AnimatedWidget to limit rebuilds, avoid heavy widget work in the animation tree, and test on low-end devices. Also prefer implicit widgets for simple changes.