Flutter: Hero Animation Errors and Best Practices

Hero animations look small on the surface, but bad configuration can easily break page transitions. Duplicate tags, mismatched widget trees, and Material incompatibilities are the most common issues.

Live Demo

You can try Hero animation in the interactive example below:

💡 If the example above doesn't load, click DartPad to run it in a new tab.

Why Does Hero Fail?

Hero finds the same tag on two screens and animates between them. If the tag is reused multiple times or the source and destination trees differ too much, the animation may not behave as expected.

This topic targets searches like "flutter hero animation error", "duplicate hero tag", and "hero widget best practices".

Common Problems

1. Duplicate Hero Tag

Hero(
  tag: 'product-image',
  child: Image.network(imageUrl),
)

Do not reuse the same tag for multiple Hero widgets on the same screen. The tag should be unique.

2. Material Mismatch

Wrapping complex Material content directly inside Hero can sometimes create visual glitches during flight. If needed, wrap it with Material(color: Colors.transparent).

3. Large Size Gaps

If the source is tiny and the destination is huge, the transition can feel abrupt. Try to keep the size change balanced.

Best Practices

• Use meaningful and unique tags.
• Keep the source and destination widgets structurally similar.
• Use consistent scaling behavior like BoxFit.cover for images.
• Pair Hero with a short, natural route transition.

Safe Hero Structure

Hero(
  tag: 'avatar-1',
  child: Material(
    color: Colors.transparent,
    child: CircleAvatar(
      radius: 24,
      backgroundImage: NetworkImage(imageUrl),
    ),
  ),
)

Debug Checklist

• Is the tag unique?
• Do both screens use the same basic widget logic?
• Does the hero child look broken during flight?
• Is the route transition too long?

Frequently Asked Questions

Why is my Hero not showing?

Usually the tags do not match, or the navigation is not connected correctly.

Does Hero work with ListView?

Yes, but list item tags must be managed carefully.

Does Hero hurt performance?

Not by itself. Most problems come from incorrect setup.

Summary

Hero animations are powerful, but they need discipline. With unique tags, consistent widget trees, and lightweight transitions, you can build a safer and more polished Flutter animation experience.