1# Explicit Animations Reference
2 
3Explicit animations provide full control using AnimationController, Tween, and animation status listeners.
4 
5## Core Components
6 
7### AnimationController
8 
9The heart of explicit animations. Manages animation lifecycle, value, and timing.
10 
11```dart
12late AnimationController _controller;
13 
14@override
15void initState() {
16  super.initState();
17  _controller = AnimationController(
18    duration: const Duration(seconds: 2),
19    vsync: this,  // Required TickerProvider
20    lowerBound: 0.0,  // Optional: default 0.0
21    upperBound: 1.0,  // Optional: default 1.0
22  );
23}
24 
25@override
26void dispose() {
27  _controller.dispose();  // ALWAYS dispose!
28  super.dispose();
29}
30```
31 
32**Lifecycle methods:**
33 
34```dart
35// Start animation forward
36_controller.forward();
37 
38// Start animation backward
39_controller.reverse();
40 
41// Stop animation
42_controller.stop();
43 
44// Repeat animation
45_controller.repeat();
46 
47// Animate to specific value
48await _controller.animateTo(0.5);
49 
50// Reset to beginning
51_controller.reset();
52 
53// Animate with physics simulation
54_controller.fling(velocity: 2.0);
55 
56// Animate with custom simulation
57_controller.animateWith(SpringSimulation(...));
58```
59 
60**Listening to changes:**
61 
62```dart
63_controller.addListener(() {
64  // Value changed - rebuild needed
65  setState(() {});
66});
67 
68_controller.addStatusListener((status) {
69  // Status changed
70  switch (status) {
71    case AnimationStatus.dismissed:
72      print('Animation dismissed (at 0)');
73      break;
74    case AnimationStatus.forward:
75      print('Animation moving forward');
76      break;
77    case AnimationStatus.reverse:
78      print('Animation moving backward');
79      break;
80    case AnimationStatus.completed:
81      print('Animation completed (at 1)');
82      break;
83  }
84});
85```
86 
87### Tween
88 
89Interpolates between begin and end values.
90 
91```dart
92// Simple tween
93animation = Tween<double>(begin: 0, end: 300).animate(_controller);
94 
95// Color tween
96animation = ColorTween(
97  begin: Colors.red,
98  end: Colors.blue,
99).animate(_controller);
100 
101// Border radius tween
102animation = BorderRadiusTween(
103  begin: BorderRadius.circular(4),
104  end: BorderRadius.circular(75),
105).animate(_controller);
106 
107// Rect tween
108animation = RectTween(
109  begin: Rect.fromLTWH(0, 0, 100, 100),
110  end: Rect.fromLTWH(100, 100, 200, 200),
111).animate(_controller);
112```
113 
114**Common Tweens:**
115- `Tween<T>` - Generic tween (use for most types)
116- `ColorTween` - Color interpolation
117- `RectTween` - Rectangle interpolation
118- `IntTween` - Integer interpolation
119- `SizeTween` - Size interpolation
120- `OffsetTween` - Offset interpolation
121- `BorderRadiusTween` - Border radius interpolation
122 
123### CurvedAnimation
124 
125Applies a curve to transform animation values.
126 
127```dart
128animation = CurvedAnimation(
129  parent: _controller,
130  curve: Curves.easeInOut,
131  reverseCurve: Curves.easeIn,  // Optional: different curve for reverse
132);
133```
134 
135**With Interval:**
136 
137```dart
138animation = CurvedAnimation(
139  parent: _controller,
140  curve: const Interval(
141    0.25,  // Start at 25% of controller
142    0.75,  // End at 75% of controller
143    curve: Curves.easeInOut,
144  ),
145);
146```
147 
148### ReverseAnimation
149 
150Reverses the parent animation.
151 
152```dart
153final forwardAnimation = Tween<double>(begin: 0, end: 1).animate(_controller);
154final reverseAnimation = ReverseAnimation(forwardAnimation);
155```
156 
157## Patterns
158 
159### AnimatedWidget Pattern
160 
161Best for reusable animated widgets. Automatically handles rebuilds.
162 
163```dart
164class AnimatedLogo extends AnimatedWidget {
165  const AnimatedLogo({super.key, required Animation<double> animation})
166    : super(listenable: animation);
167 
168  @override
169  Widget build(BuildContext context) {
170    final animation = listenable as Animation<double>;
171    return Center(
172      child: Container(
173        height: animation.value,
174        width: animation.value,
175        child: const FlutterLogo(),
176      ),
177    );
178  }
179}
180 
181// Usage
182@override
183Widget build(BuildContext context) {
184  return AnimatedLogo(animation: _animation);
185}
186```
187 
188### AnimatedBuilder Pattern
189 
190Best for complex widgets. Separates animation logic from widget logic.
191 
192```dart
193class GrowTransition extends StatelessWidget {
194  const GrowTransition({
195    required this.child,
196    required this.animation,
197    super.key,
198  });
199 
200  final Widget child;
201  final Animation<double> animation;
202 
203  @override
204  Widget build(BuildContext context) {
205    return Center(
206      child: AnimatedBuilder(
207        animation: animation,
208        builder: (context, child) {
209          return SizedBox(
210            height: animation.value,
211            width: animation.value,
212            child: child,
213          );
214        },
215        child: child,
216      ),
217    );
218  }
219}
220 
221// Usage
222@override
223Widget build(BuildContext context) {
224  return GrowTransition(
225    animation: _animation,
226    child: const LogoWidget(),
227  );
228}
229```
230 
231**Why pass child twice?**
232The `child` parameter to `AnimatedBuilder` is passed to the `builder` function, allowing the child to be built once and reused, rather than rebuilt every animation frame.
233 
234### Multiple Animations Pattern
235 
236Animate multiple properties from single controller.
237 
238```dart
239class MultiPropertyAnimation extends AnimatedWidget {
240  const MultiPropertyAnimation({super.key, required Animation<double> animation})
241    : super(listenable: animation);
242 
243  static final _opacityTween = Tween<double>(begin: 0.1, end: 1);
244  static final _sizeTween = Tween<double>(begin: 0, end: 300);
245  static final _colorTween = ColorTween(
246    begin: Colors.red,
247    end: Colors.blue,
248  );
249 
250  @override
251  Widget build(BuildContext context) {
252    final animation = listenable as Animation<double>;
253    return Center(
254      child: Opacity(
255        opacity: _opacityTween.evaluate(animation),
256        child: Container(
257          height: _sizeTween.evaluate(animation),
258          width: _sizeTween.evaluate(animation),
259          decoration: BoxDecoration(
260            color: _colorTween.evaluate(animation),
261            borderRadius: BorderRadius.circular(12),
262          ),
263          child: const FlutterLogo(),
264        ),
265      ),
266    );
267  }
268}
269```
270 
271## Built-in Transitions
272 
273Flutter provides pre-built transitions for common use cases.
274 
275### FadeTransition
276 
277```dart
278FadeTransition(
279  opacity: _animation,
280  child: const FlutterLogo(),
281)
282```
283 
284### ScaleTransition
285 
286```dart
287ScaleTransition(
288  scale: _animation,
289  child: const FlutterLogo(),
290)
291```
292 
293### SlideTransition
294 
295```dart
296SlideTransition(
297  position: Tween<Offset>(
298    begin: Offset(0, 1),
299    end: Offset.zero,
300  ).animate(_animation),
301  child: const FlutterLogo(),
302)
303```
304 
305### SizeTransition
306 
307```dart
308SizeTransition(
309  sizeFactor: _animation,
310  axis: Axis.vertical,
311  child: const FlutterLogo(),
312)
313```
314 
315### RotationTransition
316 
317```dart
318RotationTransition(
319  turns: _animation,
320  child: const FlutterLogo(),
321)
322```
323 
324### DecoratedBoxTransition
325 
326```dart
327DecoratedBoxTransition(
328  decoration: DecorationTween(
329    begin: BoxDecoration(color: Colors.red),
330    end: BoxDecoration(color: Colors.blue),
331  ).animate(_animation),
332  child: const FlutterLogo(),
333)
334```
335 
336### PositionedTransition
337 
338```dart
339Stack(
340  children: [
341    PositionedTransition(
342      rect: RelativeRectTween(
343        begin: RelativeRect.fill(calculateRect(context, startPosition)),
344        end: RelativeRect.fill(calculateRect(context, endPosition)),
345      ).animate(_animation),
346      child: const FlutterLogo(),
347    ),
348  ],
349)
350```
351 
352## Animation Status Handling
353 
354### Basic Status Loop
355 
356```dart
357_animation.addStatusListener((status) {
358  if (status == AnimationStatus.completed) {
359    _controller.reverse();
360  } else if (status == AnimationStatus.dismissed) {
361    _controller.forward();
362  }
363});
364```
365 
366### One-way Animation
367 
368```dart
369_animation.addStatusListener((status) {
370  if (status == AnimationStatus.completed) {
371    _controller.stop();  // Or navigate, show dialog, etc.
372  }
373});
374```
375 
376### Reset and Repeat
377 
378```dart
379_animation.addStatusListener((status) {
380  if (status == AnimationStatus.completed) {
381    _controller.reset();
382    _controller.forward();
383  }
384});
385```
386 
387## Performance Best Practices
388 
389### DO
390 
391- Always dispose AnimationController
392- Use `AnimatedWidget` or `AnimatedBuilder` instead of `setState()` in listeners
393- Minimize widget rebuilds during animation
394- Use static Tweens when possible (avoid recreating)
395- Profile with Flutter DevTools
396- Use `timeDilation` for debugging
397 
398### DON'T
399 
400- Forget to dispose controllers (memory leak)
401- Call `setState()` in animation listeners unnecessarily
402- Create complex widget trees inside animation builds
403- Animate too many widgets simultaneously
404- Use animation values directly in expensive operations
405 
406### Performance Pattern: RepaintBoundary
407 
408```dart
409RepaintBoundary(
410  child: AnimatedBuilder(
411    animation: _controller,
412    builder: (context, child) {
413      return ExpensiveWidget();
414    },
415  ),
416)
417```
418 
419## Debugging
420 
421### Slow Animations
422 
423```dart
424void main() {
425  timeDilation = 10.0;  // 10x slower
426  runApp(MyApp());
427}
428```
429 
430### Print Animation Values
431 
432```dart
433_controller.addListener(() {
434  print('Animation value: ${_controller.value}');
435});
436 
437_animation.addStatusListener((status) {
438  print('Animation status: $status');
439});
440```
441 
442### Flutter DevTools Performance Overlay
443 
4441. Run app in debug mode
4452. Press 'p' to toggle performance overlay
4463. Look for "GPU UI" and "GPU Raster" graphs
4474. Aim for 60fps (16.67ms per frame)
448 
449## Common Patterns
450 
451### Fade In Then Slide Up
452 
453```dart
454_animation = Tween<double>(begin: 0, end: 1).animate(
455  CurvedAnimation(
456    parent: _controller,
457    curve: const Interval(0.0, 0.5, curve: Curves.easeIn),
458  ),
459);
460 
461_slideAnimation = Tween<Offset>(
462  begin: Offset(0, 0.5),
463  end: Offset.zero,
464).animate(
465  CurvedAnimation(
466    parent: _controller,
467    curve: const Interval(0.3, 1.0, curve: Curves.easeOut),
468  ),
469);
470```
471 
472### Bounce Effect
473 
474```dart
475_animation = CurvedAnimation(
476  parent: _controller,
477  curve: Curves.elasticOut,
478);
479```
480 
481### Shake Effect
482 
483```dart
484class ShakeCurve extends Curve {
485  @override
486  double transform(double t) {
487    return sin(t * pi * 2);
488  }
489}
490 
491_animation = CurvedAnimation(
492  parent: _controller,
493  curve: ShakeCurve(),
494);
495```
496 
497### Parallax Scrolling
498 
499```dart
500class ParallaxWidget extends StatelessWidget {
501  const ParallaxWidget({
502    required this.animation,
503    required this.child,
504    super.key,
505  });
506 
507  final Animation<double> animation;
508  final Widget child;
509 
510  @override
511  Widget build(BuildContext context) {
512    return AnimatedBuilder(
513      animation: animation,
514      builder: (context, child) {
515        return Transform.translate(
516          offset: Offset(0, animation.value * 50),
517          child: child,
518        );
519      },
520      child: child,
521    );
522  }
523}
524```
525 
526## Comparison: Implicit vs Explicit
527 
528| Feature | Implicit | Explicit |
529|---------|----------|-----------|
530| Controller | None needed | AnimationController required |
531| Setup | Simple | More complex |
532| Control | Limited (duration, curve) | Full (lifecycle, status, physics) |
533| Multiple Properties | AnimatedContainer only | Unlimited |
534| Performance | Good | Excellent (with patterns) |
535| Reusability | Widget-based | Component-based |
536| State Monitoring | Limited (onEnd) | Full (status listeners) |
537 
538## When to Use Explicit Animations
539 
540Use explicit animations when:
541- Need full control over animation lifecycle
542- Animating multiple properties
543- Need to react to animation state changes
544- Creating reusable animation components
545- Need complex timing or sequencing
546- Performance is critical
547- Want physics-based or custom animations
548 
549Use implicit animations when:
550- Simple, one-off animations
551- Animation triggered by state change
552- No need for fine-grained control
553- Want simple, declarative code
554