1# Staggered Animations Reference
2 
3Staggered animations run multiple animations with different timing offsets, creating sequential or overlapping visual effects.
4 
5## Core Concept
6 
7All animations share one `AnimationController`. Each animation has an `Interval` defining when it starts and ends within the controller's timeline.
8 
9## Basic Staggered Animation
10 
11### Two-Property Stagger
12 
13```dart
14class StaggeredFadeSlide extends StatelessWidget {
15  const StaggeredFadeSlide({super.key, required this.controller});
16 
17  final AnimationController controller;
18 
19  // Fade in first (0.0 - 0.5 of controller)
20  late final Animation<double> opacity = Tween<double>(begin: 0, end: 1).animate(
21    CurvedAnimation(
22      parent: controller,
23      curve: const Interval(0.0, 0.5, curve: Curves.easeIn),
24    ),
25  );
26 
27  // Slide in later (0.25 - 1.0 of controller)
28  late final Animation<Offset> slide = Tween<Offset>(
29    begin: Offset(0, 0.5),
30    end: Offset.zero,
31  ).animate(
32    CurvedAnimation(
33      parent: controller,
34      curve: const Interval(0.25, 1.0, curve: Curves.easeOut),
35    ),
36  );
37 
38  @override
39  Widget build(BuildContext context) {
40    return AnimatedBuilder(
41      animation: controller,
42      builder: (context, child) {
43        return FadeTransition(
44          opacity: opacity,
45          child: SlideTransition(
46            position: slide,
47            child: child,
48          ),
49        );
50      },
51      child: const Text('Staggered animation'),
52    );
53  }
54}
55```
56 
57### Multiple Intervals Example
58 
59```dart
60class MultiPropertyStagger extends StatelessWidget {
61  const MultiPropertyStagger({super.key, required this.controller});
62 
63  final AnimationController controller;
64 
65  // Opacity: 0.0 - 0.1 (10%)
66  late final Animation<double> opacity = Tween<double>(begin: 0, end: 1).animate(
67    CurvedAnimation(
68      parent: controller,
69      curve: const Interval(0.0, 0.1, curve: Curves.ease),
70    ),
71  );
72 
73  // Width: 0.125 - 0.25 (12.5% - 25%)
74  late final Animation<double> width = Tween<double>(begin: 50, end: 150).animate(
75    CurvedAnimation(
76      parent: controller,
77      curve: const Interval(0.125, 0.25, curve: Curves.ease),
78    ),
79  );
80 
81  // Height: 0.25 - 0.375 (25% - 37.5%)
82  late final Animation<double> height = Tween<double>(begin: 50, end: 150).animate(
83    CurvedAnimation(
84      parent: controller,
85      curve: const Interval(0.25, 0.375, curve: Curves.ease),
86    ),
87  );
88 
89  // Border radius: 0.375 - 0.5 (37.5% - 50%)
90  late final Animation<BorderRadius?> borderRadius = BorderRadiusTween(
91    begin: BorderRadius.circular(4),
92    end: BorderRadius.circular(75),
93  ).animate(
94    CurvedAnimation(
95      parent: controller,
96      curve: const Interval(0.375, 0.5, curve: Curves.ease),
97    ),
98  );
99 
100  // Color: 0.5 - 0.625 (50% - 62.5%)
101  late final Animation<Color?> color = ColorTween(
102    begin: Colors.red,
103    end: Colors.orange,
104  ).animate(
105    CurvedAnimation(
106      parent: controller,
107      curve: const Interval(0.5, 0.625, curve: Curves.ease),
108    ),
109  );
110 
111  @override
112  Widget build(BuildContext context) {
113    return AnimatedBuilder(
114      animation: controller,
115      builder: (context, child) {
116        return Opacity(
117          opacity: opacity.value,
118          child: Container(
119            width: width.value,
120            height: height.value,
121            decoration: BoxDecoration(
122              color: color.value,
123              borderRadius: borderRadius.value,
124            ),
125            child: child,
126          ),
127        );
128      },
129      child: const FlutterLogo(),
130    );
131  }
132}
133```
134 
135## Controller Setup
136 
137### Single Controller
138 
139```dart
140class _StaggerState extends State<StaggerWidget>
141    with SingleTickerProviderStateMixin {
142  late AnimationController _controller;
143 
144  @override
145  void initState() {
146    super.initState();
147    _controller = AnimationController(
148      duration: const Duration(milliseconds: 2000),
149      vsync: this,
150    );
151    _controller.forward();
152  }
153 
154  @override
155  void dispose() {
156    _controller.dispose();
157    super.dispose();
158  }
159 
160  @override
161  Widget build(BuildContext context) {
162    return StaggerAnimation(controller: _controller.view);
163  }
164}
165```
166 
167### Multiple Controllers
168 
169For independent animation sequences:
170 
171```dart
172class _ComplexStaggerState extends State<ComplexStaggerWidget>
173    with TickerProviderStateMixin {
174  late AnimationController _fadeInController;
175  late AnimationController _slideController;
176 
177  @override
178  void initState() {
179    super.initState();
180 
181    _fadeInController = AnimationController(
182      duration: const Duration(milliseconds: 500),
183      vsync: this,
184    );
185 
186    _slideController = AnimationController(
187      duration: const Duration(milliseconds: 500),
188      vsync: this,
189    );
190 
191    // Start fade, then slide
192    _fadeInController.forward().then((_) {
193      _slideController.forward();
194    });
195  }
196 
197  @override
198  void dispose() {
199    _fadeInController.dispose();
200    _slideController.dispose();
201    super.dispose();
202  }
203}
204```
205 
206## Interval Timing
207 
208### Understanding Interval
209 
210```dart
211Interval(
212  0.25,  // Start at 25% of controller duration
213  0.75,  // End at 75% of controller duration
214  curve: Curves.easeInOut,
215)
216```
217 
218**Example:** If controller duration is 2000ms:
219- Animation starts at 500ms (0.25 * 2000)
220- Animation ends at 1500ms (0.75 * 2000)
221- Animation takes 1000ms (1500 - 500)
222 
223### Overlapping Intervals
224 
225```dart
226// Animation 1: 0.0 - 0.5 (first half)
227anim1 = Tween<double>(begin: 0, end: 1).animate(
228  CurvedAnimation(
229    parent: controller,
230    curve: const Interval(0.0, 0.5),
231  ),
232);
233 
234// Animation 2: 0.3 - 0.8 (starts before anim1 ends)
235anim2 = Tween<double>(begin: 0, end: 1).animate(
236  CurvedAnimation(
237    parent: controller,
238    curve: const Interval(0.3, 0.8),
239  ),
240);
241 
242// Animation 3: 0.6 - 1.0 (starts after anim1 ends)
243anim3 = Tween<double>(begin: 0, end: 1).animate(
244  CurvedAnimation(
245    parent: controller,
246    curve: const Interval(0.6, 1.0),
247  ),
248);
249```
250 
251### Gaps Between Animations
252 
253```dart
254// Animation 1: 0.0 - 0.4
255// Gap: 0.4 - 0.5
256// Animation 2: 0.5 - 0.9
257 
258anim1 = Tween<double>(begin: 0, end: 1).animate(
259  CurvedAnimation(
260    parent: controller,
261    curve: const Interval(0.0, 0.4),
262  ),
263);
264 
265anim2 = Tween<double>(begin: 0, end: 1).animate(
266  CurvedAnimation(
267    parent: controller,
268    curve: const Interval(0.5, 0.9),
269  ),
270);
271```
272 
273## Staggered List Animation
274 
275### Menu Items Animation
276 
277```dart
278class StaggeredMenu extends StatefulWidget {
279  const StaggeredMenu({super.key});
280 
281  static const _menuItems = [
282    'Home',
283    'Profile',
284    'Settings',
285    'About',
286  ];
287 
288  @override
289  State<StaggeredMenu> createState() => _StaggeredMenuState();
290}
291 
292class _StaggeredMenuState extends State<StaggeredMenu>
293    with SingleTickerProviderStateMixin {
294  static const _itemDelayTime = Duration(milliseconds: 50);
295  static const _itemAnimationTime = Duration(milliseconds: 250);
296 
297  late AnimationController _controller;
298  late List<Animation<double>> _itemAnimations;
299 
300  @override
301  void initState() {
302    super.initState();
303    _controller = AnimationController(
304      duration: _itemAnimationTime +
305          (_itemDelayTime * (StaggeredMenu._menuItems.length - 1)),
306      vsync: this,
307    );
308 
309    _itemAnimations = StaggeredMenu._menuItems.map((item) {
310      final index = StaggeredMenu._menuItems.indexOf(item);
311      return Tween<double>(begin: 0, end: 1).animate(
312        CurvedAnimation(
313          parent: _controller,
314          curve: Interval(
315            index * 0.1,  // Start later for each item
316            (index * 0.1) + 0.4,  // Each takes 40% of controller
317            curve: Curves.easeOut,
318          ),
319        ),
320      );
321    }).toList();
322 
323    _controller.forward();
324  }
325 
326  @override
327  void dispose() {
328    _controller.dispose();
329    super.dispose();
330  }
331 
332  @override
333  Widget build(BuildContext context) {
334    return ListView.builder(
335      itemCount: StaggeredMenu._menuItems.length,
336      itemBuilder: (context, index) {
337        return AnimatedBuilder(
338          animation: _controller,
339          builder: (context, child) {
340            return SlideTransition(
341              position: Tween<Offset>(
342                begin: Offset(1.0, 0),
343                end: Offset.zero,
344              ).animate(CurvedAnimation(
345                parent: _controller,
346                curve: Interval(
347                  index * 0.1,
348                  (index * 0.1) + 0.4,
349                  curve: Curves.easeOut,
350                ),
351              )),
352              child: FadeTransition(
353                opacity: _itemAnimations[index],
354                child: child,
355              ),
356            );
357          },
358          child: ListTile(
359            title: Text(StaggeredMenu._menuItems[index]),
360          ),
361        );
362      },
363    );
364  }
365}
366```
367 
368### Grid Animation
369 
370```dart
371class StaggeredGrid extends StatefulWidget {
372  const StaggeredGrid({super.key, required this.itemCount});
373 
374  final int itemCount;
375 
376  @override
377  State<StaggeredGrid> createState() => _StaggeredGridState();
378}
379 
380class _StaggeredGridState extends State<StaggeredGrid>
381    with SingleTickerProviderStateMixin {
382  late AnimationController _controller;
383  late List<Animation<double>> _animations;
384 
385  @override
386  void initState() {
387    super.initState();
388    _controller = AnimationController(
389      duration: const Duration(milliseconds: 1500),
390      vsync: this,
391    );
392 
393    _animations = List.generate(widget.itemCount, (index) {
394      return Tween<double>(begin: 0, end: 1).animate(
395        CurvedAnimation(
396          parent: _controller,
397          curve: Interval(
398            index / widget.itemCount,
399            (index / widget.itemCount) + 0.3,
400            curve: Curves.easeOut,
401          ),
402        ),
403      );
404    });
405 
406    _controller.forward();
407  }
408 
409  @override
410  void dispose() {
411    _controller.dispose();
412    super.dispose();
413  }
414 
415  @override
416  Widget build(BuildContext context) {
417    return GridView.builder(
418      gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
419        crossAxisCount: 2,
420      ),
421      itemCount: widget.itemCount,
422      itemBuilder: (context, index) {
423        return AnimatedBuilder(
424          animation: _controller,
425          builder: (context, child) {
426            return FadeTransition(
427              opacity: _animations[index],
428              child: ScaleTransition(
429                scale: _animations[index],
430                child: child,
431              ),
432            );
433          },
434          child: Card(
435            child: Center(child: Text('Item $index')),
436          ),
437        );
438      },
439    );
440  }
441}
442```
443 
444## Complex Staggered Patterns
445 
446### Sequential Completion
447 
448```dart
449animation1 = Tween<double>(begin: 0, end: 1).animate(
450  CurvedAnimation(
451    parent: controller,
452    curve: const Interval(0.0, 0.3),
453  ),
454);
455 
456animation2 = Tween<double>(begin: 0, end: 1).animate(
457  CurvedAnimation(
458    parent: controller,
459    curve: const Interval(0.3, 0.6),
460  ),
461);
462 
463animation3 = Tween<double>(begin: 0, end: 1).animate(
464  CurvedAnimation(
465    parent: controller,
466    curve: const Interval(0.6, 1.0),
467  ),
468);
469```
470 
471### Ripple Effect
472 
473```dart
474// Center expands first, then outward
475for (int i = 0; i < itemCount; i++) {
476  final distance = (i - centerIndex).abs();
477  animations[i] = Tween<double>(begin: 0, end: 1).animate(
478    CurvedAnimation(
479      parent: controller,
480      curve: Interval(
481        distance * 0.1,
482        (distance * 0.1) + 0.3,
483        curve: Curves.easeOut,
484      ),
485    ),
486  );
487}
488```
489 
490### Staggered Reveal
491 
492```dart
493// Reveal items one by one from top
494for (int i = 0; i < itemCount; i++) {
495  animations[i] = CurvedAnimation(
496    parent: controller,
497    curve: Interval(
498      i * 0.1,
499      (i * 0.1) + 0.15,
500      curve: Curves.easeOut,
501    ),
502  );
503}
504 
505// Use for opacity or transform
506Opacity(opacity: animations[i].value)
507```
508 
509## Duration Calculation
510 
511### Calculate Total Duration
512 
513```dart
514const itemDelay = Duration(milliseconds: 50);
515const itemAnimationTime = Duration(milliseconds: 250);
516const itemCount = 10;
517 
518final totalDuration = itemAnimationTime +
519    (itemDelay * (itemCount - 1));
520 
521// 250ms + (50ms * 9) = 700ms
522```
523 
524### Using in Controller
525 
526```dart
527_controller = AnimationController(
528  duration: totalDuration,
529  vsync: this,
530);
531```
532 
533### Dynamic Duration
534 
535```dart
536late AnimationController _controller;
537late Duration _totalDuration;
538 
539@override
540void initState() {
541  super.initState();
542 
543  final itemCount = _items.length;
544  const itemDelay = Duration(milliseconds: 50);
545  const itemAnimationTime = Duration(milliseconds: 250);
546 
547  _totalDuration = itemAnimationTime + (itemDelay * (itemCount - 1));
548 
549  _controller = AnimationController(
550    duration: _totalDuration,
551    vsync: this,
552  );
553 
554  // Create animations...
555  _controller.forward();
556}
557```
558 
559## Repeating Staggered Animations
560 
561### Loop on Completion
562 
563```dart
564_controller.addStatusListener((status) {
565  if (status == AnimationStatus.completed) {
566    _controller.reset();
567    _controller.forward();
568  }
569});
570```
571 
572### Ping-Pong (Forward and Reverse)
573 
574```dart
575_controller.addStatusListener((status) {
576  if (status == AnimationStatus.completed) {
577    _controller.reverse();
578  } else if (status == AnimationStatus.dismissed) {
579    _controller.forward();
580  }
581});
582```
583 
584## Debugging Staggered Animations
585 
586### Slow Animation
587 
588```dart
589void main() {
590  timeDilation = 10.0;  // 10x slower
591  runApp(MyApp());
592}
593```
594 
595### Print Interval Ranges
596 
597```dart
598for (int i = 0; i < _animations.length; i++) {
599  final anim = _animations[i] as CurvedAnimation;
600  print('Animation $i: ${anim.curve}');
601}
602 
603// Output:
604// Animation 0: Interval(0.0, 0.4, Curves.easeOut)
605// Animation 1: Interval(0.1, 0.5, Curves.easeOut)
606// ...
607```
608 
609### Visualize Animation State
610 
611```dart
612class DebugStaggeredWidget extends StatelessWidget {
613  const DebugStaggeredWidget({super.key, required this.controller, required this.animations});
614 
615  final AnimationController controller;
616  final List<Animation<double>> animations;
617 
618  @override
619  Widget build(BuildContext context) {
620    return Column(
621      children: [
622        for (int i = 0; i < animations.length; i++)
623          Text('Animation $i: ${animations[i].value.toStringAsFixed(2)}'),
624      ],
625    );
626  }
627}
628```
629 
630## Performance Best Practices
631 
632### DO
633 
634- Use one controller when animations are related
635- Calculate total duration correctly
636- Use `AnimatedBuilder` for optimal rebuilds
637- Profile with Flutter DevTools
638- Test on various devices
639- Consider reducing animation complexity on low-end devices
640 
641### DON'T
642 
643- Create too many controllers unnecessarily
644- Forget to dispose controllers
645- Use complex widget trees inside staggered animations
646- Animate too many items simultaneously (jank)
647- Use very long durations without good reason
648 
649## Common Patterns
650 
651### Loading Animation
652 
653```dart
654// Dot 1: 0.0 - 0.3
655// Dot 2: 0.1 - 0.4
656// Dot 3: 0.2 - 0.5
657// Repeat forever
658```
659 
660### Success Animation Sequence
661 
662```dart
663// Checkmark appears: 0.0 - 0.3
664// "Success!" text fades in: 0.2 - 0.5
665// Confetti falls: 0.3 - 1.0
666```
667 
668### Onboarding Steps
669 
670```dart
671// Step 1: 0.0 - 0.25
672// Step 2: 0.25 - 0.5
673// Step 3: 0.5 - 0.75
674// Step 4: 0.75 - 1.0
675```
676 
677## Accessibility
678 
679- Respect `MediaQuery.disableAnimations` setting
680- Provide alternative to complex staggered animations
681- Ensure content remains accessible during animation
682- Test with screen readers
683 
684## Advanced Techniques
685 
686### Conditional Staggering
687 
688```dart
689// Show animations based on device performance
690final isLowEnd = Platform.isAndroid && deviceInfo.version.sdkInt < 21;
691 
692final staggerDelay = isLowEnd
693    ? Duration(milliseconds: 100)  // Slower on low-end
694    : Duration(milliseconds: 50);
695```
696 
697### Adaptive Staggering
698 
699```dart
700// Adjust based on screen size
701final screenWidth = MediaQuery.of(context).size.width;
702final itemsPerRow = screenWidth ~/ 150;
703 
704// Calculate stagger based on grid position
705final row = index ~/ itemsPerRow;
706final col = index % itemsPerRow;
707final startDelay = (row * 0.2) + (col * 0.05);
708```
709 
710### Physics-Influenced Staggering
711 
712```dart
713// Use spring physics for staggered elements
714for (int i = 0; i < itemCount; i++) {
715  animations[i] = Tween<double>(begin: 0, end: 1).animate(
716    CurvedAnimation(
717      parent: controller,
718      curve: Interval(
719        i * 0.05,
720        (i * 0.05) + 0.5,
721        curve: Curves.elasticOut,
722      ),
723    ),
724  );
725}
726```
727