1# Hero Animations Reference
2 
3Hero animations create shared element transitions between screens, making elements appear to "fly" from one route to another.
4 
5## Core Concept
6 
7Use two `Hero` widgets with matching `tag` in different routes. Flutter automatically animates the transition between them.
8 
9## Basic Hero Animation
10 
11### Simple Image Transition
12 
13**Source route (list screen):**
14```dart
15GestureDetector(
16  onTap: () {
17    Navigator.of(context).push(
18      MaterialPageRoute<void>(
19        builder: (context) => const DetailScreen(),
20      ),
21    );
22  },
23  child: Hero(
24    tag: 'hero-image',
25    child: Image.asset('images/thumbnail.png'),
26  ),
27)
28```
29 
30**Destination route (detail screen):**
31```dart
32Scaffold(
33  appBar: AppBar(title: const Text('Detail')),
34  body: GestureDetector(
35    onTap: () => Navigator.of(context).pop(),
36    child: Hero(
37      tag: 'hero-image',  // Same tag!
38      child: Image.asset('images/thumbnail.png'),
39    ),
40  ),
41)
42```
43 
44### Custom PhotoHero Widget
45 
46Reusable hero widget for images:
47 
48```dart
49class PhotoHero extends StatelessWidget {
50  const PhotoHero({
51    super.key,
52    required this.photo,
53    this.onTap,
54    required this.width,
55  });
56 
57  final String photo;
58  final VoidCallback? onTap;
59  final double width;
60 
61  @override
62  Widget build(BuildContext context) {
63    return SizedBox(
64      width: width,
65      child: Hero(
66        tag: photo,
67        child: Material(
68          color: Colors.transparent,
69          child: InkWell(
70            onTap: onTap,
71            child: Image.asset(
72              photo,
73              fit: BoxFit.contain,
74            ),
75          ),
76        ),
77      ),
78    );
79  }
80}
81```
82 
83**Usage in source route:**
84```dart
85class SourceScreen extends StatelessWidget {
86  const SourceScreen({super.key});
87 
88  @override
89  Widget build(BuildContext context) {
90    return Scaffold(
91      appBar: AppBar(title: const Text('Gallery')),
92      body: GridView.builder(
93        gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
94          crossAxisCount: 2,
95        ),
96        itemCount: 10,
97        itemBuilder: (context, index) {
98          return PhotoHero(
99            photo: 'images/photo_$index.png',
100            width: 100,
101            onTap: () {
102              Navigator.of(context).push(
103                MaterialPageRoute<void>(
104                  builder: (context) => DetailScreen(photo: 'images/photo_$index.png'),
105                ),
106              );
107            },
108          );
109        },
110      ),
111    );
112  }
113}
114```
115 
116**Usage in destination route:**
117```dart
118class DetailScreen extends StatelessWidget {
119  const DetailScreen({super.key, required this.photo});
120 
121  final String photo;
122 
123  @override
124  Widget build(BuildContext context) {
125    return Scaffold(
126      appBar: AppBar(title: const Text('Detail')),
127      body: Center(
128        child: PhotoHero(
129          photo: photo,
130          width: 300,
131          onTap: () => Navigator.of(context).pop(),
132        ),
133      ),
134    );
135  }
136}
137```
138 
139## Hero Tag Best Practices
140 
141### Using Object as Tag
142 
143For unique, consistent tags:
144 
145```dart
146// Data model
147class Photo {
148  final String url;
149  final String id;
150 
151  Photo({required this.url, required this.id});
152}
153 
154// Source
155Hero(
156  tag: photo.id,  // Use unique identifier
157  child: Image.network(photo.url),
158)
159 
160// Destination
161Hero(
162  tag: photo.id,  // Same unique identifier
163  child: Image.network(photo.url),
164)
165```
166 
167### Using Data Object as Tag
168 
169When data object is consistent:
170 
171```dart
172// Source
173Hero(
174  tag: photo,  // Photo object must be same instance or implement ==
175  child: Image.network(photo.url),
176)
177 
178// Destination
179Hero(
180  tag: photo,  // Same Photo object
181  child: Image.network(photo.url),
182)
183```
184 
185**Important:** If using object as tag, ensure proper `==` and `hashCode` implementation.
186 
187## Custom Hero Flight Path
188 
189### MaterialRectArcTween (Default)
190 
191```dart
192Hero(
193  tag: 'hero-image',
194  flightShuttleBuilder: (flightContext, animation, direction, fromContext, toContext) {
195    return AnimatedBuilder(
196      animation: animation,
197      builder: (context, child) {
198        return Transform.scale(
199          scale: animation.value,
200          child: child,
201        );
202      },
203      child: child,
204    );
205  },
206  createRectTween: (begin, end) {
207    return MaterialRectArcTween(begin: begin, end: end);
208  },
209  child: Image.asset('image.png'),
210)
211```
212 
213### MaterialRectCenterArcTween
214 
215Center-based interpolation (good for maintaining aspect ratio):
216 
217```dart
218static RectTween _createRectTween(Rect? begin, Rect? end) {
219  return MaterialRectCenterArcTween(begin: begin, end: end);
220}
221 
222Hero(
223  tag: 'hero-image',
224  createRectTween: _createRectTween,
225  child: Image.asset('image.png'),
226)
227```
228 
229### Custom RectTween
230 
231For complete control:
232 
233```dart
234class LinearRectTween extends Tween<Rect> {
235  LinearRectTween({required Rect begin, required Rect end})
236    : super(begin: begin, end: end);
237 
238  @override
239  Rect lerp(double t) => Rect.lerp(begin!, end!, t);
240}
241 
242Hero(
243  tag: 'hero-image',
244  createRectTween: (begin, end) => LinearRectTween(begin: begin, end: end),
245  child: Image.asset('image.png'),
246)
247```
248 
249## Radial Hero Animation
250 
251Transform from circle to rectangle during transition.
252 
253### RadialExpansion Widget
254 
255```dart
256import 'dart:math' as math;
257 
258class RadialExpansion extends StatelessWidget {
259  const RadialExpansion({
260    super.key,
261    required this.maxRadius,
262    this.child,
263  }) : clipRectSize = 2.0 * (maxRadius / math.sqrt2);
264 
265  final double maxRadius;
266  final double clipRectSize;
267  final Widget? child;
268 
269  @override
270  Widget build(BuildContext context) {
271    return ClipOval(
272      child: Center(
273        child: SizedBox(
274          width: clipRectSize,
275          height: clipRectSize,
276          child: ClipRect(child: child),
277        ),
278      ),
279    );
280  }
281}
282```
283 
284### Radial Photo Widget
285 
286```dart
287class RadialPhoto extends StatelessWidget {
288  const RadialPhoto({
289    super.key,
290    required this.photo,
291    this.onTap,
292  });
293 
294  final String photo;
295  final VoidCallback? onTap;
296 
297  @override
298  Widget build(BuildContext context) {
299    return Material(
300      color: Theme.of(context).primaryColor.withValues(alpha: 0.25),
301      child: InkWell(
302        onTap: onTap,
303        child: Image.asset(
304          photo,
305          fit: BoxFit.contain,
306        ),
307      ),
308    );
309  }
310}
311```
312 
313### Complete Radial Hero Example
314 
315```dart
316class RadialHeroAnimation extends StatelessWidget {
317  const RadialHeroAnimation({super.key});
318 
319  @override
320  Widget build(BuildContext context) {
321    return Scaffold(
322      appBar: AppBar(title: const Text('Radial Hero')),
323      body: ListView(
324        children: List.generate(6, (index) {
325          final photo = 'images/photo_$index.png';
326          return Hero(
327            tag: photo,
328            createRectTween: _createRectTween,
329            flightShuttleBuilder: (flightContext, animation, direction, fromContext, toContext) {
330              return AnimatedBuilder(
331                animation: animation,
332                builder: (context, child) {
333                  return FadeTransition(
334                    opacity: animation,
335                    child: child,
336                  );
337                },
338                child: child,
339              );
340            },
341            child: RadialExpansion(
342              maxRadius: 120,
343              child: RadialPhoto(
344                photo: photo,
345                onTap: () {
346                  Navigator.of(context).push(
347                    MaterialPageRoute<void>(
348                      builder: (context) => DetailScreen(photo: photo),
349                    ),
350                  );
351                },
352              ),
353            ),
354          );
355        }),
356      ),
357    );
358  }
359 
360  static RectTween _createRectTween(Rect? begin, Rect? end) {
361    return MaterialRectCenterArcTween(begin: begin, end: end);
362  }
363}
364 
365class DetailScreen extends StatelessWidget {
366  const DetailScreen({super.key, required this.photo});
367 
368  final String photo;
369 
370  @override
371  Widget build(BuildContext context) {
372    return Scaffold(
373      appBar: AppBar(title: const Text('Detail')),
374      body: Center(
375        child: Hero(
376          tag: photo,
377          createRectTween: RadialHeroAnimation._createRectTween,
378          child: SizedBox(
379            width: 300,
380            height: 300,
381            child: RadialPhoto(
382              photo: photo,
383              onTap: () => Navigator.of(context).pop(),
384            ),
385          ),
386        ),
387      ),
388    );
389  }
390}
391```
392 
393## Custom Placeholder During Flight
394 
395### flightShuttleBuilder
396 
397Customize hero appearance during flight:
398 
399```dart
400Hero(
401  tag: 'hero-image',
402  flightShuttleBuilder: (flightContext, animation, direction, fromContext, toContext) {
403    // fromContext - source hero's context
404    // toContext - destination hero's context
405    // direction - HeroFlightDirection.push or pop
406    // animation - Animation<double> for the flight
407 
408    return AnimatedBuilder(
409      animation: animation,
410      builder: (context, child) {
411        return Transform.rotate(
412          angle: animation.value * math.pi,
413          child: child,
414        );
415      },
416      child: child,
417    );
418  },
419  child: Image.asset('image.png'),
420)
421```
422 
423### Replace Entire Hero During Flight
424 
425```dart
426Hero(
427  tag: 'hero-image',
428  flightShuttleBuilder: (flightContext, animation, direction, fromContext, toContext) {
429    // Show different widget during flight
430    return Container(
431      width: 100,
432      height: 100,
433      color: Colors.blue,
434    );
435  },
436  child: Image.asset('image.png'),
437)
438```
439 
440## Transition Settings
441 
442### Animation Duration
443 
444```dart
445MaterialApp(
446  // Set global hero animation duration
447  theme: ThemeData(
448    pageTransitionsTheme: PageTransitionsTheme(
449      builders: {
450        TargetPlatform.android: ZoomPageTransitionsBuilder(),
451        TargetPlatform.iOS: CupertinoPageTransitionsBuilder(),
452      },
453    ),
454  ),
455)
456```
457 
458### Custom PageTransitionBuilder
459 
460```dart
461class CustomHeroTransitionBuilder extends PageTransitionsBuilder {
462  @override
463  Widget buildTransitions<T>(
464    PageRoute<T> route,
465    BuildContext? secondaryContext,
466    Widget child,
467  ) {
468    return FadeUpwardsPageTransitionsBuilder().buildTransitions(
469      route,
470      secondaryContext,
471      child,
472    );
473  }
474}
475```
476 
477## Hero Mode
478 
479### Disable Hero Animations
480 
481```dart
482HeroMode(
483  enabled: false,  // Disable all child hero animations
484  child: ListView(
485    children: [
486      Hero(tag: 'image1', child: Image.asset('1.png')),
487      Hero(tag: 'image2', child: Image.asset('2.png')),
488    ],
489  ),
490)
491```
492 
493### Conditional Hero Mode
494 
495```dart
496HeroMode(
497  enabled: !_disableAnimations,
498  child: Hero(tag: 'image', child: Image.asset('image.png')),
499)
500```
501 
502## Debugging Hero Animations
503 
504### Slow Animation
505 
506```dart
507void main() {
508  timeDilation = 10.0;  // 10x slower
509  runApp(MyApp());
510}
511```
512 
513### Visualize Hero Bounds
514 
515```dart
516void main() {
517  debugPaintSizeEnabled = true;
518  runApp(MyApp());
519}
520```
521 
522### Print Hero Tags
523 
524```dart
525class DebugHero extends StatelessWidget {
526  const DebugHero({
527    super.key,
528    required this.tag,
529    required this.child,
530  });
531 
532  final Object tag;
533  final Widget child;
534 
535  @override
536  Widget build(BuildContext context) {
537    print('Building Hero with tag: $tag');
538    return Hero(tag: tag, child: child);
539  }
540}
541```
542 
543## Best Practices
544 
545### DO
546 
547- Use unique, consistent tags (often the data object itself)
548- Keep hero widget trees similar between routes
549- Wrap images in `Material` with transparent color for "pop" effect
550- Use `timeDilation` to debug transitions
551- Consider `createRectTween` for custom flight paths
552- Use `flightShuttleBuilder` for custom flight appearance
553 
554### DON'T
555 
556- Use duplicate tags (conflicts!)
557- Change hero structure significantly between routes (jarring transition)
558- Forget `Material` wrapper (no splash effect)
559- Use very large images in heroes (performance)
560- Ignore aspect ratio during transition (distortion)
561 
562## Common Patterns
563 
564### Grid to Fullscreen Image
565 
566**Grid item:**
567```dart
568PhotoHero(
569  photo: photo.url,
570  width: 150,  // Smaller in grid
571  onTap: () => Navigator.push(..., detailScreen),
572)
573```
574 
575**Fullscreen:**
576```dart
577PhotoHero(
578  photo: photo.url,
579  width: MediaQuery.of(context).size.width,  // Full width
580  onTap: () => Navigator.pop(),
581)
582```
583 
584### List Header to Page Header
585 
586**List:**
587```dart
588Hero(
589  tag: 'header',
590  child: SizedBox(
591    height: 200,
592    child: Image.asset('header.jpg'),
593  ),
594)
595```
596 
597**Page:**
598```dart
599Hero(
600  tag: 'header',
601  child: SizedBox(
602    height: 300,  // Larger on detail page
603    child: Image.asset('header.jpg'),
604  ),
605)
606```
607 
608### Shared Element with Content Update
609 
610```dart
611// In both routes
612Hero(
613  tag: 'card',
614  child: Card(
615    child: Column(
616      children: [
617        Image.asset('image.png'),
618        Text(showDetails ? 'Full description...' : 'Brief description'),
619      ],
620    ),
621  ),
622)
623```
624 
625## Performance Tips
626 
627- Optimize hero images (compress, lazy load)
628- Use `RepaintBoundary` around hero children if needed
629- Test on low-end devices
630- Profile with Flutter DevTools Performance overlay
631- Avoid complex widget trees inside hero
632 
633## Accessibility
634 
635- Respect `MediaQuery.disableAnimations` setting
636- Consider alternative navigation for users who prefer no animations
637- Ensure hero content remains accessible during transition
638- Test with screen readers
639 
640## Advanced Techniques
641 
642### Multiple Heroes on Same Route
643 
644```dart
645class PhotoDetail extends StatelessWidget {
646  const PhotoDetail({super.key, required this.photos});
647 
648  final List<String> photos;
649 
650  @override
651  Widget build(BuildContext context) {
652    return Stack(
653      children: [
654        // Main photo hero
655        Positioned.fill(
656          child: Hero(
657            tag: photos[0],
658            child: Image.asset(photos[0]),
659          ),
660        ),
661        // Overlay hero (e.g., like button)
662        Positioned(
663          top: 16,
664          right: 16,
665          child: Hero(
666            tag: 'like-button',
667            child: Icon(Icons.favorite),
668          ),
669        ),
670      ],
671    );
672  }
673}
674```
675 
676### Nested Heroes
677 
678```dart
679Hero(
680  tag: 'parent',
681  child: Card(
682    child: Column(
683      children: [
684        Hero(
685          tag: 'child-image',
686          child: Image.asset('image.png'),
687        ),
688        Hero(
689          tag: 'child-title',
690          child: Text('Title'),
691        ),
692      ],
693    ),
694  ),
695)
696```
697 
698### Hero with Scroll Views
699 
700```dart
701class ScrollableHero extends StatelessWidget {
702  @override
703  Widget build(BuildContext context) {
704    return CustomScrollView(
705      slivers: [
706        SliverAppBar(
707          expandedHeight: 300,
708          flexibleSpace: FlexibleSpaceBar(
709            background: Hero(
710              tag: 'header-image',
711              child: Image.asset('header.jpg', fit: BoxFit.cover),
712            ),
713          ),
714        ),
715        SliverList(
716          delegate: SliverChildListDelegate([
717            // Content
718          ]),
719        ),
720      ],
721    );
722  }
723}
724```
725