Flutter animations

Flutter Animations

Instructions

Animations give Flutter apps their identity, but done wrong they are the #1 source of jank. Pick the lowest-power tool that fits.

1. The Ladder (pick the simplest)

1. Implicit — AnimatedContainer, AnimatedOpacity, AnimatedAlign, AnimatedPositioned, AnimatedDefaultTextStyle. Change a field, Flutter tweens it. Use for state-driven tweaks.
2. Tween shortcuts — TweenAnimationBuilder<T> when no widget-level implicit exists.
3. Explicit — AnimationController + Tween + AnimatedBuilder/FadeTransition/SlideTransition. Use for coordinated or repeating animations.
4. Hero — Hero(tag: ...) for shared-element transitions across routes.
5. Physics — SpringSimulation, FrictionSimulation via AnimationController.animateWith for natural motion.

2. AnimationController Lifecycle

class _FadeInState extends State<FadeIn> with SingleTickerProviderStateMixin {
  late final _ctrl = AnimationController(
    vsync: this,
    duration: const Duration(milliseconds: 300),
  )..forward();

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

  @override
  Widget build(BuildContext context) =>
      FadeTransition(opacity: _ctrl, child: widget.child);
}

• Always dispose() the controller.
• Use SingleTickerProviderStateMixin for one controller, TickerProviderStateMixin for multiple.
• For controllers driven by Riverpod, create them in a Notifier with ref.onDispose(ctrl.dispose).

3. Transitions — Use the Built-Ins

Prefer FadeTransition, SlideTransition, ScaleTransition, RotationTransition, SizeTransition over AnimatedBuilder — they are RepaintBoundary-aware and rebuild minimal subtrees.

4. Curves Matter

• Curves.easeOutCubic for UI elements entering.
• Curves.easeInCubic for leaving.
• Curves.easeInOutCubic for state changes.
• Avoid Curves.linear — feels robotic.
• Clamp durations to 150–400ms for UI feedback; longer only for storytelling.

5. 120Hz / ProMotion

• Enable ImpellerEnabled (default on iOS, opt-in on Android) for consistent frame pacing.
• Use SchedulerBinding.instance.addPostFrameCallback for layout-dependent animations.
• Avoid Opacity on animating subtrees — it forces an offscreen layer. Use FadeTransition (uses RenderAnimatedOpacity).
• Avoid animating ClipRRect, ShaderMask, or BackdropFilter — expensive on the raster thread.

6. Staggered Animations

Use Interval(start, end, curve: ...) on a single controller to stagger children, instead of multiple controllers.

final fadeIn = CurvedAnimation(parent: _ctrl, curve: const Interval(0.0, 0.5, curve: Curves.easeOut));
final slideIn = CurvedAnimation(parent: _ctrl, curve: const Interval(0.3, 1.0, curve: Curves.easeOutCubic));

7. Lottie, Rive, and Native Feel

• Rive (rive package) — state-machine-driven vector animations, GPU-efficient, designer-friendly. Preferred for complex illustrations.
• Lottie (lottie package) — legacy JSON animations; fine for static loops, heavier than Rive.
• For native-style page transitions, use PageTransitionsTheme with platform-specific builders.

8. Hero Pitfalls

• Both source and destination Hero must share the exact same tag.
• The child should be the same type (or wrap both in an identical Material ancestor) to avoid mid-flight rebuilds.
• Use flightShuttleBuilder to customize the in-flight widget (e.g., cross-fade).

9. Testing Animations

• Use tester.pump(const Duration(milliseconds: 150)) — do NOT pumpAndSettle for infinite animations (it hangs).
• Assert the controller value at intermediate points.
• For golden tests of mid-flight frames, pin a specific animation.value and capture.

10. Checklist

• Every AnimationController is disposed.
• Used the simplest option on the ladder (implicit → explicit → physics).
• No Opacity / Clip* / BackdropFilter on animating hot subtrees.
• Duration 150–400ms for UI feedback, curves are eased.
• Hero tags unique per screen pair; tested both directions.